<HTML><HEAD>
	
	<TITLE>Orange Command Line Tools Help</TITLE>
	<META NAME="AUTHOR" CONTENT="">
	<META NAME="GENERATOR" CONTENT="HelpScribble 7.8.3 from http://www.helpscribble.com/">
</HEAD>
<BODY BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#800080" ALINK="#FF0000">
<A NAME="hs10"></A>
<FONT FACE="Arial" COLOR="#0000FF" SIZE="5"><B>Welcome to Command Line Tools Help</B></FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">In the background, OCIDE uses several command line tools known as the Orange Toolchain to perform various functions such as compiling and linking.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">This document describes the Orange Toolchain in some detail.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">This is somewhat of a classic toolchain, except there is an addition of a linker post-processing or download stage to manage turning the linker output file into an executable program.&nbsp;&nbsp; There are several linker post-processing stages to target different platforms, including a post-processing stage that will generate various types of HEX file formats.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">General tools compile or assemble code, and manage the resulting object files</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> </FONT><A HREF="#hs30"><FONT FACE="Arial" SIZE="2">OCC</FONT></A><FONT FACE="Arial" SIZE="2"> is an optimizing C compiler which handles the various flavors of C from C89 through C11.</FONT><BR>
<FONT FACE="Arial" SIZE="2"> </FONT><A HREF="#hs170"><FONT FACE="Arial" SIZE="2">OAsm</FONT></A><FONT FACE="Arial" SIZE="2"> is an x86 assembler.&nbsp; It uses a syntax that is very similar to the Netwide Assembler (NASM)</FONT><BR>
<FONT FACE="Arial" SIZE="2"> </FONT><A HREF="#hs490"><FONT FACE="Arial" SIZE="2">OLib</FONT></A><FONT FACE="Arial" SIZE="2"> is an object file librarian.</FONT><BR>
<FONT FACE="Arial" SIZE="2"> </FONT><A HREF="#hs420"><FONT FACE="Arial" SIZE="2">OLink</FONT></A><FONT FACE="Arial" SIZE="2"> is an object file linker object file linker.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Linker postprocessing tools take the linker output, and make some sort of device or OS-specific binary image that serves as the final executable\ image.</FONT><BR>
<FONT FACE="Arial" SIZE="2"> </FONT><A HREF="#hs510"><FONT FACE="Arial" SIZE="2">DLHex</FONT></A><FONT FACE="Arial" SIZE="2"> is the utility to make hex and binary files, for ROM-based images</FONT><BR>
<FONT FACE="Arial" SIZE="2"> </FONT><A HREF="#hs530"><FONT FACE="Arial" SIZE="2">DLMZ</FONT></A><FONT FACE="Arial" SIZE="2"> is the utility to make 16-bit MSDOS executables.&nbsp; The compiler will not output 16 bit code but this may be used with the assembler.</FONT><BR>
<FONT FACE="Arial" SIZE="2"> </FONT><A HREF="#hs520"><FONT FACE="Arial" SIZE="2">DLLE</FONT></A><FONT FACE="Arial" SIZE="2"> is the utility to make 32-bit MSDOS executables that aren't windows compatible.</FONT><BR>
<FONT FACE="Arial" SIZE="2"> </FONT><A HREF="#hs540"><FONT FACE="Arial" SIZE="2">DLPE</FONT></A><FONT FACE="Arial" SIZE="2"> is the utility to make Windows 32-bit executables.&lt;</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">There are several external utilities that the IDE doesn't use directly, but can be useful from the command line</FONT><BR>
<FONT FACE="Arial" SIZE="2"> </FONT><A HREF="#hs470"><FONT FACE="Arial" SIZE="2">OCPP</FONT></A><FONT FACE="Arial" SIZE="2"> is a C and assembly language preprocessor.&nbsp; It understands C89, C99, C11, and OAsm preprocessor directive syntaxes.</FONT><BR>
<FONT FACE="Arial" SIZE="2"> </FONT><A HREF="#hs390"><FONT FACE="Arial" SIZE="2">OGrep</FONT></A><FONT FACE="Arial" SIZE="2"> looks for regular expressions within source code files.</FONT><BR>
<FONT FACE="Arial" SIZE="2"> </FONT><A HREF="#hs460"><FONT FACE="Arial" SIZE="2">OMake</FONT></A><FONT FACE="Arial" SIZE="2"> is a make utility very similar to GNU make.</FONT><BR>
<BR>
<BR>
<FONT FACE="Arial" SIZE="2">Some utilities are specific to developing WIN32 programs:</FONT><BR>
<FONT FACE="Arial" SIZE="2"> </FONT><A HREF="#hs480"><FONT FACE="Arial" SIZE="2">OImpLib</FONT></A><FONT FACE="Arial" SIZE="2"> is a WIN32 import librarian capable of managing imports from DLL and .DEF files.</FONT><BR>
<FONT FACE="Arial" SIZE="2"> </FONT><A HREF="#hs500"><FONT FACE="Arial" SIZE="2">ORC</FONT></A><FONT FACE="Arial" SIZE="2"> is a WIN32 resource compiler.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Here are the </FONT><A HREF="#hs20"><FONT FACE="Arial" SIZE="2">license terms</FONT></A><BR>

<BR><BR><BR>
<A NAME="hs20"></A>
<FONT FACE="Arial" COLOR="#008000" SIZE="2">The BSD Licensing terms are as follows:</FONT><BR>
<BR>
<FONT FACE="Arial" COLOR="#008000" SIZE="2"> Software License Agreement (BSD License)</FONT><BR>
<FONT FACE="Arial" COLOR="#008000" SIZE="2">&nbsp;</FONT><BR>
<FONT FACE="Arial" COLOR="#008000" SIZE="2"> Copyright (c) 1997-2013, David Lindauer, (LADSoft).</FONT><BR>
<FONT FACE="Arial" COLOR="#008000" SIZE="2"> All rights reserved.</FONT><BR>
<FONT FACE="Arial" COLOR="#008000" SIZE="2">&nbsp;</FONT><BR>
<FONT FACE="Arial" COLOR="#008000" SIZE="2"> Redistribution and use of this software in source and binary forms,&nbsp;</FONT><BR>
<FONT FACE="Arial" COLOR="#008000" SIZE="2">&nbsp;&nbsp;&nbsp; with or without modification, are permitted provided that the following&nbsp;</FONT><BR>
<FONT FACE="Arial" COLOR="#008000" SIZE="2">&nbsp;&nbsp;&nbsp; conditions are met:</FONT><BR>
<FONT FACE="Arial" COLOR="#008000" SIZE="2">&nbsp;</FONT><BR>
<FONT FACE="Arial" COLOR="#008000" SIZE="2"> * Redistributions of source code must retain the above</FONT><BR>
<FONT FACE="Arial" COLOR="#008000" SIZE="2">&nbsp;&nbsp; copyright notice, this list of conditions and the</FONT><BR>
<FONT FACE="Arial" COLOR="#008000" SIZE="2">&nbsp;&nbsp; following disclaimer.</FONT><BR>
<FONT FACE="Arial" COLOR="#008000" SIZE="2">&nbsp;</FONT><BR>
<FONT FACE="Arial" COLOR="#008000" SIZE="2"> * Redistributions in binary form must reproduce the above</FONT><BR>
<FONT FACE="Arial" COLOR="#008000" SIZE="2">&nbsp;&nbsp; copyright notice, this list of conditions and the</FONT><BR>
<FONT FACE="Arial" COLOR="#008000" SIZE="2">&nbsp;&nbsp; following disclaimer in the documentation and/or other</FONT><BR>
<FONT FACE="Arial" COLOR="#008000" SIZE="2">&nbsp;&nbsp; materials provided with the distribution.</FONT><BR>
<FONT FACE="Arial" COLOR="#008000" SIZE="2">&nbsp;</FONT><BR>
<FONT FACE="Arial" COLOR="#008000" SIZE="2"> * Neither the name of LADSoft nor the names of its</FONT><BR>
<FONT FACE="Arial" COLOR="#008000" SIZE="2">&nbsp;&nbsp; contributors may be used to endorse or promote products</FONT><BR>
<FONT FACE="Arial" COLOR="#008000" SIZE="2">&nbsp;&nbsp; derived from this software without specific prior</FONT><BR>
<FONT FACE="Arial" COLOR="#008000" SIZE="2">&nbsp;&nbsp; written permission of LADSoft.</FONT><BR>
<FONT FACE="Arial" COLOR="#008000" SIZE="2">&nbsp;</FONT><BR>
<FONT FACE="Arial" COLOR="#008000" SIZE="2"> THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"&nbsp;</FONT><BR>
<FONT FACE="Arial" COLOR="#008000" SIZE="2">&nbsp;&nbsp;&nbsp; AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,&nbsp;</FONT><BR>
<FONT FACE="Arial" COLOR="#008000" SIZE="2">&nbsp;&nbsp;&nbsp; THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR&nbsp;</FONT><BR>
<FONT FACE="Arial" COLOR="#008000" SIZE="2">&nbsp;&nbsp;&nbsp; PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER&nbsp;</FONT><BR>
<FONT FACE="Arial" COLOR="#008000" SIZE="2">&nbsp;&nbsp;&nbsp; OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,&nbsp;</FONT><BR>
<FONT FACE="Arial" COLOR="#008000" SIZE="2">&nbsp;&nbsp;&nbsp; EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,&nbsp;</FONT><BR>
<FONT FACE="Arial" COLOR="#008000" SIZE="2">&nbsp;&nbsp;&nbsp; PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;&nbsp;</FONT><BR>
<FONT FACE="Arial" COLOR="#008000" SIZE="2">&nbsp;&nbsp;&nbsp; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,&nbsp;</FONT><BR>
<FONT FACE="Arial" COLOR="#008000" SIZE="2">&nbsp;&nbsp;&nbsp; WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR&nbsp;</FONT><BR>
<FONT FACE="Arial" COLOR="#008000" SIZE="2">&nbsp;&nbsp;&nbsp; OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF</FONT><BR>
<FONT FACE="Arial" COLOR="#008000" SIZE="2"> ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
</FONT>
<BR><BR><BR>
<A NAME="hs30"></A>
<FONT FACE="Arial" COLOR="#0000FF" SIZE="5"><B>OCC</B></FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">OCC is an optimiziing compiler capable of compilng C language files written to the C99 and C11 standards.&nbsp; However in its default mode, it compiles to the older standard for which most legacy programs are written.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">OCC currently only generates code for the x86 series processor. Together with the rest of the toolchain and supplied libraries, it can be used to create WIN32 program files. This toolchain also includes extenders necessary for running WIN32 applications on MSDOS, so OCC may be run on MSDOS and used to generate MSDOS programs as well.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">By default OCC will spawn the necessary subprograms to generate a completed executable from a source file.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">A companion program, OCL, may be used to generate MSDOS executables which depend on one of a variety of MSDOS extenders.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">The general form of an OCC </FONT><A HREF="#hs40"><FONT FACE="Arial" SIZE="2">Command Line</FONT></A><FONT FACE="Arial" SIZE="2"> is:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">OCC [options] filename-list</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Where filename-list gives a list of files to compile.&nbsp;</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">In addition to support for the C99 standard, OCC supports a variety of the usual </FONT><A HREF="#hs160"><FONT FACE="Arial" SIZE="2">compiler extensions</FONT></A><FONT FACE="Arial" SIZE="2">&nbsp; found in MSDOS and WIN32 compilers.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">OCC also supports a range of </FONT><A HREF="#hs150"><FONT FACE="Arial" SIZE="2">#pragma preprocessor directives</FONT></A><FONT FACE="Arial" SIZE="2"> to allow some level of control over the generated code. Such directives include support for structure alignment, having the CRTL run routines as part of its normal startup and shutdown process, and so forth.
</FONT>
<BR><BR><BR>
<A NAME="hs40"></A>
<FONT FACE="Arial" COLOR="#0000FF" SIZE="5"><B>Command Line</B></FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">OCC has a variety of command line parameters, most of which aren't needed to just compile a file. It will also allow you to specify multiple input files. The current default for OCC is to generate executable files. While processing the command line, OCC may encounter a command to process command line arguments from a file.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">The general format of the command line is as follows:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">OCC [parameters] list of files</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">The list of files can be a list of one or more C language files. C++ language files are partially supported, but the C++ support is minimal at this time. If you don't specify an extension on the command line it will default to .C; it will detect a .CPP extension and activate C++ mode as required.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">OCC will accept response files with a list of command line options. To use a response file, prefix its name with '@':</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">OCC [parameters] @resp.cc</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">There are a variety of parameters that can be set. Help is available for the following:</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> </FONT><A HREF="#hs50"><FONT FACE="Arial" SIZE="2">Output Control</FONT></A><BR>
<FONT FACE="Arial" SIZE="2"> </FONT><A HREF="#hs60"><FONT FACE="Arial" SIZE="2">Error Control</FONT></A><BR>
<FONT FACE="Arial" SIZE="2"> </FONT><A HREF="#hs70"><FONT FACE="Arial" SIZE="2">List File Control</FONT></A><BR>
<FONT FACE="Arial" SIZE="2"> </FONT><A HREF="#hs80"><FONT FACE="Arial" SIZE="2">Preprocessor File Contro</FONT></A><FONT FACE="Arial" SIZE="2">l</FONT><BR>
<FONT FACE="Arial" SIZE="2"> </FONT><A HREF="#hs90"><FONT FACE="Arial" SIZE="2">Compilation Modes</FONT></A><BR>
<FONT FACE="Arial" SIZE="2"> </FONT><A HREF="#hs100"><FONT FACE="Arial" SIZE="2">Defining Macros</FONT></A><BR>
<FONT FACE="Arial" SIZE="2"> </FONT><A HREF="#hs110"><FONT FACE="Arial" SIZE="2">Specifying Include Paths</FONT></A><BR>
<FONT FACE="Arial" SIZE="2"> </FONT><A HREF="#hs120"><FONT FACE="Arial" SIZE="2">Translating Trigraphs</FONT></A><BR>
<FONT FACE="Arial" SIZE="2"> </FONT><A HREF="#hs130"><FONT FACE="Arial" SIZE="2">Code Generation Parameters</FONT></A><BR>
<FONT FACE="Arial" SIZE="2"> </FONT><A HREF="#hs140"><FONT FACE="Arial" SIZE="2">Optimizer Parameters</FONT></A><FONT FACE="Arial" COLOR="#800000" SIZE="2">
</FONT>
<BR><BR><BR>
<A NAME="hs50"></A>
<FONT FACE="Arial" COLOR="#0000FF" SIZE="5"><B>Output Control</B></FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">The following switches are available for output control:</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"><B>/c</B> generate object file only</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> Causes OCC to not generate an EXE file automatically. Useful when compiling many files prior to a later link stage.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> </FONT><FONT FACE="Courier New" SIZE="2">OCC /c hello.c</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> generates a file hello.o instead of generating hello.exe</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"><B>/o</B>&nbsp; set output file name</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> Causes OCC to rename the output file. If generating an EXE output, OCC will rename the exe file. If generating an object (OBJ) file, OCC will rename the obj file. Note that you cannot set the output file name for a group of files unless you are generating an EXE file.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> </FONT><FONT FACE="Courier New" SIZE="2">OCC /ohi hello.c</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> generates an EXE file called HI.EXE.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> whereas&nbsp;</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> </FONT><FONT FACE="Courier New" SIZE="2">OCC /c /obeep hello.c</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> generates an object file called BEEP.O.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"><B>/S</B> generate assembly language file only</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> Causes OCC to generate an assembly language file in NASM format, but no object or EXE files</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> </FONT><FONT FACE="Courier" SIZE="2">OCC /c hello.c</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> generates a file HELLO.ASM</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"><B>/s</B> generate intermediate assembly language file</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> OCC will generate an executable file by compiling via assembly. The intermediate assembly language file will remain after compilation.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> </FONT><FONT FACE="Courier New" SIZE="2">OCC /s hello.c</FONT><BR>
<FONT FACE="Arial" SIZE="2">&nbsp;</FONT><BR>
<FONT FACE="Arial" SIZE="2"> generates the files HELLO.O, HELLO.ASM, and HELLO.EXE</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"><B>/v</B> generate debug information</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> OCC will generate debug information for use by the IDE.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">/W&nbsp; set exe file type</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> When OCC is generating an EXE file, several formats are possible. These are as follows:</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> /Wd - generate a WIN32 DLL program&nbsp;</FONT><BR>
<FONT FACE="Arial" SIZE="2"> /Wdc - generate a WIN32 DLL program, use CRTDLL run time library</FONT><BR>
<FONT FACE="Arial" SIZE="2"> /Wdl - generate a WIN32 DLL program, use LSCRTL run time library</FONT><BR>
<FONT FACE="Arial" SIZE="2"> /Wdm - generate a WIN32 DLL program, use MSVCRT run time library</FONT><BR>
<FONT FACE="Arial" SIZE="2"> /Wc - generate a WIN32 console program</FONT><BR>
<FONT FACE="Arial" SIZE="2"> /Wcc - generate a WIN32 console program, use CRTDLL run time library</FONT><BR>
<FONT FACE="Arial" SIZE="2"> /Wcl - generate a WIN32 console program, use LSCRTL run time library</FONT><BR>
<FONT FACE="Arial" SIZE="2"> /Wcm - generate a WIN32 console program, use MSVCRT run time library</FONT><BR>
<FONT FACE="Arial" SIZE="2"> /Wg - generate a WIN32 gui program</FONT><BR>
<FONT FACE="Arial" SIZE="2"> /Wgc - generate a WIN32 gui program, use CRTDLL run time library</FONT><BR>
<FONT FACE="Arial" SIZE="2"> /Wgl - generate a WIN32 gui program, use LSCRTL run time library</FONT><BR>
<FONT FACE="Arial" SIZE="2"> /Wgm - generate a WIN32 gui program, use MSVCRT run time library</FONT><BR>
<FONT FACE="Arial" SIZE="2"> /We - generate an MSDOS program (using Tran's PMODE)</FONT><BR>
<FONT FACE="Arial" SIZE="2"> /Wa - generate an MSDOS program (using DOS32A)</FONT><BR>
<FONT FACE="Arial" SIZE="2"> /Wh - generate an MSDOS program (using HXDOS/WIN32 runtime)</FONT><BR>
<FONT FACE="Arial" SIZE="2"> /Wr - generete a RAW program</FONT><BR>
<FONT FACE="Arial" SIZE="2"> /Wx - generate an MSDOS program (using HXDOS/DOS runtime)</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">&nbsp; OCC /Wcl hello.c</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">&nbsp; generates a win32 console program hello.exe, which will use the LSCRTL.DLL run time library.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> Note: when compiling files for use with the LSCRTL.DLL, one of the switches /Wdl /Wcl or /Wgl must be present to indicate to the compiler that linkage will be against that library. Failing to use one of these switches can result in errant run-time behavior.
</FONT>
<BR><BR><BR>
<A NAME="hs60"></A>
<FONT FACE="Arial" COLOR="#0000FF" SIZE="5"><B>Error Control</B></FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">The following switches are available for error messages control:</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"><B>+e</B>&nbsp; put the compiler errors in a file.&nbsp;</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> For each file processed, OCC will create a file with the same name as the original source with the extension.'.err'. The contents of this file will be a listing of any errors or warnings which occurred during the compile. For example:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> OCC +e myfile.c</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> results in myfile.err</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"><B>+Q</B> Quiet mode</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> Don't display errors or warnings on the console. Generally this is used in conjunction with the +e switch. For example:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> OCC +e +Q myfile.c</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> puts the errors in a file, without displaying them on the console.</FONT><BR>
<BR>
<BR>
<FONT FACE="Arial" SIZE="2"><B>/E[+-]nn</B> error control</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> nn is the maximum number of errors before the&nbsp; compile fails; if + is specified extended warnings will be shown that are normally disabled by default. If - is specified warnings will be turned off.&nbsp; For example:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> OCC /E+44 myfile.c</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> enables extended warnings and limits the number of&nbsp; errors to 44. By default only 25 errors will be shown and then the compiler will abort and</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> OCC /E- myfile.c</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> compiles myfile.c without displaying any warnings.
</FONT>
<BR><BR><BR>
<A NAME="hs70"></A>
<FONT FACE="Arial" COLOR="#0000FF" SIZE="5"><B>List File Control</B></FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">The following switches are available for list file control:</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"><B>+l</B> create a listing file&nbsp;</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> For each file processed, OCC will create a file with the same name as the original source with the extension.&nbsp; '.lst'. The contents of this file will be various information gathered about the program which was processed. For example:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> OCC +l myfile.c</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> results in myfile.lst
</FONT>
<BR><BR><BR>
<A NAME="hs80"></A>
<FONT FACE="Arial" COLOR="#0000FF" SIZE="5"><B>Preprocessor File Control</B></FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">The following switches are available for preprocessor control</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"><B>+i</B> create a file with preprocessed text.&nbsp;</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> For each file processed, OCC will create a file with the same name as the original source with the extension.&nbsp; '.i'. The contents of this file will be the source code, with each identifier which corresponded to a macro expanded out to its full value. For example:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> OCC +i myfile.c</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> results in myfile.i where each #defined identifier replaced with its value.</FONT><BR>
<BR>

<BR><BR><BR>
<A NAME="hs90"></A>
<FONT FACE="Arial" COLOR="#0000FF" SIZE="5"><B>Compilation Modes</B></FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">The following switches are available to set the language compatibility mode:</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"><B>+A</B> disable non-ansi extensions</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> By default the compiler allows several extensions to ansi, to make coding easier. If you want strict adherence to ansi, use this switch. For example:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> OCC +A myfunc.c</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> will enable ANSI mode</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"><B>+9</B> C99 Compatibility</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> By default the compiler compiles for pre-99 standard. If you want extended features available in the later C99 standard, use this switch. For example:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> OCC /9 myfunc.c</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> Will enable C99 mode.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"><B>+1</B> C11 Compatibility</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> Enables compatibility with the C11 standard.&nbsp; For example:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> OCC /1 myfunc.c</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> Will enable C11 mode.
</FONT>
<BR><BR><BR>
<A NAME="hs100"></A>
<FONT FACE="Arial" COLOR="#0000FF" SIZE="5"><B>Defining Macros</B></FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">The following switches are useful for definint macros:</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"><B>/Dxxx</B> define a macro</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> This switch defines a macro as if a #define statement had been used somewhere in the source. It is useful for building different versions of a program without modifying the source files between compiles. Note that you may not give macros defined this way a value. For example:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> OCC /DORANGE myfunc.c</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">&nbsp; is equivalent to placing the following statement at the beginning of the source file and compiling it.</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> #define ORANGE&nbsp;</FONT><BR>

<BR><BR><BR>
<A NAME="hs110"></A>
<FONT FACE="Arial" COLOR="#0000FF" SIZE="5"><B>Specifying Include Paths</B></FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">The following switches are useful for specifying where to find #included files.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"><B>/Ipath</B> specify include path.&nbsp;</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> If your file uses headers that aren't in the directory you are running Orange C from, you will have to tell it what directory to look in. You can have multiple search directories by using a semicolon between the directory names. If there are multiple files with the same name in different directories being searched, CC386 will use the first instance of the file it finds by searching the path in order. For example:</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> </FONT><FONT FACE="Courier New" SIZE="2">OCC /I..\include;..\source;c:\libraries\include myfile.c</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> Will search the paths ..\include , ..\source, and c:\libraries\include in that order. Note that you generally don't have to specify a path to the OCC compiler header files such as stdio.h, as they will be added to the list of paths automatically
</FONT>
<BR><BR><BR>
<A NAME="hs120"></A>
<FONT FACE="Arial" COLOR="#0000FF" SIZE="5"><B>Translating Trigraphs</B></FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">The following switches are available to aid in translating trigraphs.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"><B>/T</B> Translate trigraphs</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> use this switch to have OCC translate trigraphs. By default OCC will not translate trigraphs for compatibility and to compile slightly faster. For example:</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> </FONT><FONT FACE="Courier New" SIZE="2">OCC /T myfile.c</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> Translates any trigraphs in the text.
</FONT>
<BR><BR><BR>
<A NAME="hs130"></A>
<FONT FACE="Arial" COLOR="#0000FF" SIZE="5"><B>Code Generation Parameters</B></FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">The following switches guide the code generation process</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"><B>/Cparams</B> specifies code generation parameters</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> Params is a list of parameters, seperated by + and - symbols. Use the + symbol to indicate a parameter is to be turned on, the minus symbol that the parameter is to be turned off. The default states of the various parameters are opposite what is shown here; i.e. this lists how to change the default state to something else.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Where params is one or more of:</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> <B>+d</B> display diagnostics</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">&nbsp; displays memory diagnostics, and some indication of what internal errors have occurred</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> <B>-b</B> merge BSS with initialized data</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> Normally there are two segments used, one for initialized data and one for uninitialized data.&nbsp; This prevents the OS from having to load uninitialized data from a file; instead the program just zeroes it during startup. This switch merges the two sections into one initialized data section.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> <B>-l</B> don't put C source in the ASM file</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> When an ASM file output option is specified, this will create an ASM file without cross-referencing the assembly code to the lines of the source file.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> <B>-m</B> don't use leading underscores</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> Normal C language procedure is to prepend each identifier with an underscore. If you want to use the compiler to generate function and variable names without an underscore use this switch. However, doing so will create an incompatibility with the run time libraries and you won't be able to link.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> <B>+r</B> reverse order of bit operations</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> Normally bit fields are allocated from least significant bit to most significant bit of whatever size variable is being used. Use this switch to reverse the order, however this may create incompatibilities with the libraries which result in code bugs.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> <B>+s</B> align stack</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> This switch causes OCC to emit code to align the stack to 16-byte boundaries. This is useful to speed up operations that involve loading and storing double-precision floating point values to auto variables. By default, the run-time libraries cause main() or WinMain() to execute with an aligned stack.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> <B>+F</B> use FLAT model in ASM file</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> When using ASM file, select FLAT model.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> <B>+I</B> use Microsoft-style imports</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> Normally the linker creates a thunk table with jump addresses that jump indirectly through the import table. This allows basic C code to compile and link.&nbsp; However some linkers do not support this and instead need the compiler to call indirectly through the import table rather than to a thunk table. Use this switch to generate code compatible with these linkers.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> <B>+M</B> generate MASM assembler file</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> <B>+N</B> generate NASM assembler file&nbsp;</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> <B>+NX</B> generate generic NASM assembler file</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> <B>+R</B> use the far keyword to create far pointers or far procedure frames</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"><B> +S</B> add stack checking code</FONT><BR>
<FONT FACE="Arial" SIZE="2">&nbsp;&nbsp;</FONT><BR>
<FONT FACE="Arial" SIZE="2"> This switch adds calls to the run-time library's stack checking code. If the stack overruns, an error is generated.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> <B>+T</B> generate TASM assembler file</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> <B>+U</B> do not assume DS == SS</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> <B>+Z</B> add profiler calls</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> This switch adds calls to a profiler module at the beginning and ending of each compiled function. This is DOS compatibility; the WIN32 profiler module does not exist at present.&nbsp; For example:</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> </FONT><FONT FACE="Courier New" SIZE="2">OCC /C+NX+Z myfile.c</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> generates generic NASM assembler module, with profiler calls inserted.
</FONT>
<BR><BR><BR>
<A NAME="hs140"></A>
<FONT FACE="Arial" COLOR="#0000FF" SIZE="5"><B>Optimizer Parameters</B></FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">The following switches deal with optimization.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"><B>/O-</B> turn off optimizer</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> This switch disables the OCC optimizer. For example:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> OCC /O- myfile.c</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> compiles a program without optimization.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> Note that specifying the <B>/v</B> switch will also turn off optimization
</FONT>
<BR><BR><BR>
<A NAME="hs150"></A>
<FONT FACE="Arial" COLOR="#0000FF" SIZE="5"><B>#Pragma statements</B></FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">#pragma preprocessor directives control the interpretation of source code, or extend the functionality of the compiler in some way.</FONT><BR>
<BR>
<BR>
<FONT FACE="Arial" COLOR="#0000FF" SIZE="2">#pragma error</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">#pragma error &lt;text&gt; allows conditional generation of errors. For example:</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> </FONT><FONT FACE="Courier New" SIZE="2">#ifndef WIN32</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> #pragma error Not a win32 program</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> #endif</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> generates a compile time error if the WIN32 macro is not defined.</FONT><BR>
<BR>
<BR>
<FONT FACE="Arial" COLOR="#0000FF" SIZE="2">#pragma warning</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">#pragma warning &lt;text&gt; allows conditional generation of errors. For example:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> #ifndef LONG</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> #pragma warning long type not defined</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> #endif</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> generates a compile time warning if the LONG macro is not defined.</FONT><BR>
<BR>
<BR>
<FONT FACE="Arial" COLOR="#0000FF" SIZE="2">#pragma aux</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">#pragma aux &lt;funcname&gt; = &lt;alias&gt;&nbsp; Creates an alias for a function. The alias name is substituted for the function name in the OBJ and ASM output files. For example:</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> </FONT><FONT FACE="Courier New" SIZE="2">#pragma aux "myfunc"="mynewname"</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> causes the linker to see the function 'myfunc' as being called 'mynewname'.&nbsp; In the source code you would still write 'myfunc' however.</FONT><BR>
<BR>
<BR>
<FONT FACE="Arial" COLOR="#0000FF" SIZE="2">#pragma pack</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">#pragma pack(n) Sets the alignment for structure members and global variables. The default alignment is 1. Changing the alignment can increase performance by causing variable and structure alignment to optimal sizes, at the expense of using extra&nbsp; memory. However, altered alignment can sometimes cause problems for example when a structure is used directly in a network packet or as the contents of a file.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> The actual alignment of any given variable depends both on the value of 'n' and on the size of the variable. CC386 will pick the minimum of the two values for the alignment of any given variable; for example if n is 2 characters will be aligned on byte boundaries and everything else will be aligned on two byte&nbsp; boundaries. If n is 4 characters will be on byte boundaries, words (short quantities) on two-byte boundaries, and dwords (ints) on four byte boundaries.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">#pragma pack() Resets the alignment to the last selection, or to the default.</FONT><BR>
<BR>
<BR>
<FONT FACE="Arial" COLOR="#0000FF" SIZE="2">#pragma startup &lt;function&gt; &lt;priority&gt;</FONT><BR>
<FONT FACE="Arial" COLOR="#0000FF" SIZE="2">#pragma rundown &lt;function&gt; &lt;priority&gt;</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> These two directives allow you to specify functions that are automatically executed by the run time library before and after the main program is executed. The priority scheme allows you to order functions in a priority order. When the RTL is executing startup or rundown functions it executes all functions at priority 1, then all functions at priority 2, then all functions at priority 3, and so forth. To have a function executed before your program runs, use #pragma startup, or to have it execute after the program exits, use #pragma rundown. You should use priorities in the range 50-200, as priorities outside that range are used by run time library functions and their execution (or lack thereof) may prevent some functions in the RTL from&nbsp; working properly. For example:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> #pragma startup myfunc 100</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> runs the function 'myfunc' after the RTL functions have initialized. Myfunc would be defined as follows:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> void myfunc(void) ;</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> Note that #pragma rundown is equivalent to atexit.&nbsp;</FONT><BR>
<BR>
<BR>
<BR>
<BR>
<BR>
<FONT FACE="Arial" SIZE="2">&gt;</FONT><BR>

<BR><BR><BR>
<A NAME="hs160"></A>
<FONT FACE="Arial" COLOR="#0000FF" SIZE="5"><B>Compiler Extensions</B></FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Extended keywords extend ANSI C in a variety of ways that are sometimes useful for example to add new functionality (such as </FONT><FONT FACE="Arial" COLOR="#0000FF" SIZE="2">alloca</FONT><FONT FACE="Arial" SIZE="2"> or </FONT><FONT FACE="Arial" COLOR="#0000FF" SIZE="2">typeof</FONT><FONT FACE="Arial" SIZE="2">) or to ease integration with operating systems and programming languages (for example </FONT><FONT FACE="Arial" COLOR="#0000FF" SIZE="2">__stdcall</FONT><FONT FACE="Arial" SIZE="2"> or </FONT><FONT FACE="Arial" COLOR="#0000FF" SIZE="2">__pascal</FONT><FONT FACE="Arial" SIZE="2">).</FONT><BR>
<BR>
<FONT FACE="Arial" COLOR="#0000FF" SIZE="2">_absolute</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> create a variable at an absolute address. Forexample:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> _absolute(0x4c21) int a ;</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> places the variable 'a' at address 0x4c21. No storage is generated for such variables and no relocation is done.</FONT><BR>
<BR>
<BR>
<FONT FACE="Arial" COLOR="#0000FF" SIZE="2">alloca</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> Allocate memory from automatic storage (the processor stack). The primary motivation for using this function is that it is much faster than the malloc() function and the allocation gets freed automatically at the end of the function.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> alloca is implicitly defined by the compiler as follows:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> void *alloca(size_t size);</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> For example:</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> </FONT><FONT FACE="Courier New" SIZE="2">int size = 24;</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> int *p = alloca(size * sizeof(int));</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> will allocate enough space to store an array of 24 integers.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> alloca allocates space without checking there is enough. If the space used by calls to this pseudo-function plus the space used by lower level functions and their data exceeds the</FONT><BR>
<FONT FACE="Arial" SIZE="2">stack size, the program will probably crash.&nbsp;</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> Memory allocated by alloca is normally freed at the end of the function it appears in, which makes it possible to allocate a lot of data in a loop. However, if a block has both a</FONT><BR>
<FONT FACE="Arial" SIZE="2">call to alloca and uses variable length arrays, at the end of the block the variable length arrays will be freed, which will also result in freeing the memory allocated by alloca.</FONT><BR>
<BR>
<BR>
<FONT FACE="Arial" COLOR="#0000FF" SIZE="2">_cdecl</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> use standard C language linking mechanism (here for compatibility with other compilers). In this linking mechanism, a leading underscore is prepended to the name, which is case sensitive. The caller is responsible for cleaning up the stack. For example:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> void _cdecl myfunc() ;</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> creates a function myfunc with standard linkage.</FONT><BR>
<BR>
<BR>
<FONT FACE="Arial" COLOR="#0000FF" SIZE="2">_export</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> make an export record for the linker to process. The current record becomes an entry in the EXE files export table. For example:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> void _export myfunc() ;</FONT><BR>
<FONT FACE="Arial" SIZE="2">&nbsp;</FONT><BR>
<FONT FACE="Arial" SIZE="2"> will cause myfunc to be an exported function.</FONT><BR>
<BR>
<BR>
<FONT FACE="Arial" COLOR="#0000FF" SIZE="2">_genbyte</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> Generate a byte of data into the code segment associated with the current function. For example:</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> </FONT><FONT FACE="Courier New" SIZE="2">void myfunc()</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> {</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> .</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> .</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> .</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> _genbyte(0x90) ;</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> .</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> .</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> .</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> }</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> puts a NOP into the code stream.</FONT><BR>
<BR>
<BR>
<FONT FACE="Arial" COLOR="#0000FF" SIZE="2">_import</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> This can be used for one of two purposes.&nbsp; First it can make import record for the linker to process, which will result in the appropriate DLL being loaded at run-time. Second, it can be used to declare a variable from a DLL so that the compiled code can access it. For example:</FONT><BR>
<BR>
<FONT FACE="Courier" SIZE="2"> int _import myvariable ;</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> declares myvariable as being imported. While</FONT><BR>
<BR>
<FONT FACE="Courier" SIZE="2"> int _import("mylib.dll") myvariable ;</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> declares myvariable as being imported from mylib.dll.</FONT><BR>
<BR>
<BR>
<FONT FACE="Arial" COLOR="#0000FF" SIZE="2">_interrupt</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> Create an interrupt function. Pushes registers and uses an IRET to return from the function. For example:</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> </FONT><FONT FACE="Courier New" SIZE="2">_interrupt void myfunc()&nbsp;</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> {</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> }</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> Creates a function myfunc which can be used as an interrupt handler.</FONT><BR>
<BR>
<BR>
<FONT FACE="Arial" SIZE="2"> _fault is similar to _interrupt, but also pops the exception word from the stack. Used when returning from certain processor fault vectors</FONT><BR>
<BR>
<BR>
<FONT FACE="Arial" COLOR="#0000FF" SIZE="2">_loadds</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> For an Interrupt function, force DS to be loaded at the beginning of the interrupt. This will be done by adding 0x10 to the CS selector to make a new DS selector. For example:</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> </FONT><FONT FACE="Courier New" SIZE="2">_loadds _interrupt void myfunc()&nbsp;</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> {</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> }</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> will create an interrupt function that loads DS</FONT><BR>
<BR>
<BR>
<FONT FACE="Arial" COLOR="#0000FF" SIZE="2">_pascal</FONT><BR>
<FONT FACE="Arial" SIZE="2">&nbsp;&nbsp;</FONT><BR>
<FONT FACE="Arial" SIZE="2"> use PASCAL linking mechanism. This linking mechanism converts the function name to upper case, removes the leading underscore, pushes arguments in reverse order from standard functions,&nbsp; and uses callee stack cleanup. For example:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> void _pascal myfunc() ;</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> Creates a function myfunc with pascal linkage.</FONT><BR>
<BR>
<BR>
<FONT FACE="Arial" COLOR="#0000FF" SIZE="2">_stdcall</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> Use STDCALL linking mechanism. This linking mechanism removes the leading underscore and uses callee stack cleanup. For example:</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> </FONT><FONT FACE="Courier New" SIZE="2">void _stdcall myfunc() ;</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> Creates a function myfunc with pascal linkage.&nbsp; This is the linkage method most windows functions use.</FONT><BR>
<BR>
<BR>
<FONT FACE="Arial" COLOR="#0000FF" SIZE="2">typeof</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> the typeof operator may be used anywhere a type declaration is used, e.g. as the base type for a variable or in a cast expression. It allows you to access the variable's type without explicitly knowing what that type is. For example:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> long double aa ;</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> typeof(aa) bb;</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> declares bb as long double type.
</FONT>
<BR><BR><BR>
<A NAME="hs170"></A>
<FONT FACE="Arial" COLOR="#0000FF" SIZE="5"><B>OAsm</B></FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">OAsm is an intel x86 assembler in the spirit of the Netwide Assembler (NASM). While it shared many features with NASM, programs written for NASM are not 100% compatible with it.&nbsp;</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">OAsm converts a textual form of processor-specific instructions into numbers the computer will understand. However, discussion of these processor-specific instructions is beyond the scope of this documentation; instead the documentation will focus on various other features OAsm presents to help easily create code and data.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">OAsm supports both 16 and 32-bit code.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">In comparison to standard Intel assemblers, OAsm shares some features. But unlike most other Intel assemblers, which keep track of the type of variables, OAsm is typeless. Which means any time a variable is used in an ambiguous context, type information has to be provided. Another major difference is the interpretation of&nbsp; brackets... in an Intel assembler brackets around simple variable names are often optional, with the assembler interpreting:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">mov ax,[myvar]</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">and</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">mov ax,myvar</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">in the same way. In these assemblers, an additional keyword offset is used to refer to a variable's address:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">mov ax,offset myvar</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">However in OAsm, the offset keyword is done away with. Instead, the brackets are given a more concrete meaning. When they exist, they indicate the value of a variable; absence of the brackets denotes the address of the variable.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">OAsm understands the usual comment syntax starting with a ';' and extending to the end of the line. For example in:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">sub eax,edx </FONT><FONT FACE="Courier New" COLOR="#00FF00" SIZE="2">; normalize</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">everything after the semicolon is a comment and is ignored.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Additionally OAsm understands C and C++ style comments since it uses an extended C language preprocessor. For example to write a block of comments use /* and */:&nbsp; Everything between the /* and the */ is a comment.&nbsp; Multiple lines may be typed between these sequences.&nbsp;&nbsp;</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">The final commenting style is the C++ double slash style, which is similar to ';' except uses a '//' sequence to delimit the beginning of the comment:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">sub eax,edx </FONT><FONT FACE="Courier New" COLOR="#00FF00" SIZE="2">// normalize</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">The general form of an OAsm </FONT><A HREF="#hs180"><FONT FACE="Arial" SIZE="2">Command Line</FONT></A><FONT FACE="Arial" SIZE="2"> is:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">OAsm [options] filename-list</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Where filename-list gives a list of files to assemble.&nbsp;</FONT><BR>
<BR>
<BR>
<FONT FACE="Arial" SIZE="2">OAsm understands several integer number formats, as well as floating point. It is also capable of evaluating complex </FONT><A HREF="#hs290"><FONT FACE="Arial" SIZE="2">expressions</FONT></A><FONT FACE="Arial" SIZE="2"> involving numbers, labels, and special symbols for things like the current program counter. Some of these expressions can be evaluated immediately; others are pushed off to the linker.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">There are three kinds of </FONT><A HREF="#hs280"><FONT FACE="Arial" SIZE="2">labels</FONT></A><FONT FACE="Arial" SIZE="2">. Each Standard label may be defined at most once in a source file. Such labels have a global context and are accessible from anywhere within the current source modules, and sometimes from other modules as well.&nbsp;</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">On the other hand Local labels inherit a context from standard labels, and may be defined multiple times provided they are defined at most once between the occurrance of any two standard labels.&nbsp;</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Non-local labels are sometimes useful - they share the idea of having a global context with standard labels, but don't start a new context for local labels.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Directives are psuedo-instructions to the assembler which guide how the assembly is done. In the most rudimentary form, they can provide a mechanism for defining numeric or textual values, or reserving space. Other directives allow breaking the code and data up into distinct sections such as CODE and DATA that can be linked against other files.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Natively, directives are always enclosed in brackets, for example to define a byte of data:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">myvar [db 44]</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">However, the directives are redefined with default macros, so that the brackets are not necessary when typing code:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">myvar db 44</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Macros are described further in the section on the </FONT><A HREF="#hs300"><FONT FACE="Arial" SIZE="2">preprocessor</FONT></A><FONT FACE="Arial" SIZE="2">.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Some of the macro redefinitions of the directives are simply a mapping from the non-bracket version to the bracketized version. Other macros are more complex, adding behavior to the assembler. For example the macros for psuedo-structures also define the structure size, and keep track of the current section and switch back to it when done.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">OAsm uses a </FONT><A HREF="#hs310"><FONT FACE="Arial" SIZE="2">C99-style</FONT></A><FONT FACE="Arial" SIZE="2"> </FONT><A HREF="#hs300"><FONT FACE="Arial" SIZE="2">preprocessor</FONT></A><FONT FACE="Arial" SIZE="2">, which has been enhanced in various ways. One difference is that instead of using '#' to start a preprocessor statement, OAsm uses '%'. This does not apply to the stringizing and tokenizing sequences however; those still use '#'.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"><A HREF="#hs320">Basic extensions to the preprocessor</FONT></A><FONT FACE="Arial" SIZE="2"> include %assign, which is similar to %define except the preprocessor will evaluate an arithmetic expression as part of the assignment. Other extensions include </FONT><A HREF="#hs380"><FONT FACE="Arial" SIZE="2">repeat blocks</FONT></A><FONT FACE="Arial" SIZE="2"> and </FONT><A HREF="#hs370"><FONT FACE="Arial" SIZE="2">multiline macros</FONT></A><FONT FACE="Arial" SIZE="2">.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">The basic </FONT><A HREF="#hs330"><FONT FACE="Arial" SIZE="2">conditional</FONT></A><FONT FACE="Arial" SIZE="2"> statements allow for a variety of ways to conditionally compile code.&nbsp; There are also various types of conditional statements which have been added to do </FONT><A HREF="#hs340"><FONT FACE="Arial" SIZE="2">textual comparisons</FONT></A><FONT FACE="Arial" SIZE="2"> and find out a </FONT><A HREF="#hs350"><FONT FACE="Arial" SIZE="2">token type</FONT></A><FONT FACE="Arial" SIZE="2">. A </FONT><A HREF="#hs360"><FONT FACE="Arial" SIZE="2">context mechanism</FONT></A><FONT FACE="Arial" SIZE="2"> useful for keeping track of assembler states.For example the context mechanism might be used with multiline macros to create a set of high level constructs such as 'if-else-endif', 'do-while' and so forth.
</FONT>
<BR><BR><BR>
<A NAME="hs180"></A>
<FONT FACE="Arial" COLOR="#0000FF" SIZE="5"><B>Command Line</B></FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">The general format of an OAsm</FONT><BR>
<FONT FACE="Arial" SIZE="2">command line is:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">OAsm [options] file-list</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">where the file-list is an arbitrary list of input files.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">For example:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">OAsm one.asm two.asm three.asm</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">assembles several files, and makes output files called ONE.O, TWO.O and THREE.O.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">The file list can have wildcards:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">OAsm *.asm</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">assembles all the files in the curent directory.</FONT><BR>
<BR>
<BR>
<FONT FACE="Arial" SIZE="2">Response files can be used as an alternate to specifying input on the command line. For example:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">OAsm @myresp.lst</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">will take command line options from myresp.lst.&nbsp; Response files aren't particularly useful with the assembler, but they are supported.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Following is a list of the command line switches OAsm supports.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"><B>-i</B> case insensity</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> if this switch is specified on the command line, </FONT><A HREF="#hs280"><FONT FACE="Arial" SIZE="2">labels</FONT></A><FONT FACE="Arial" SIZE="2"> will be treated as case insensitive. This can allow easier linkage between modules which use different case. Note that case insensitivity only extends to labels; preprocessor symbols are always case-sensitive in OAsm.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"><B>-e</B> preprocess only</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> if this switch is specified on the assembler command line, OAsm will act as a preprocessor and not perform the actual assembly phase.&nbsp; In preprocessor mode, the full functionality of the preprocessor is available, when it does not rely on information that would only be&nbsp; available while assemblying the file. Specifically, the preprocessor is fully functional, except that expressions that refer to labels or program counter locations will result in an error when used for example with the %assign preprocessor statement.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"><B>-oname</B> specifying output file name</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> By default, OAsm will take the input file name, and replace the extension with the extension .o.&nbsp; However in some cases it is useful to be able to specify the output file name with this switch. The specified name can have its extension specified, or it can be typed without an extension to allow OAsm to add the .o extension.&nbsp; OAsm is only capable of producing object files.&nbsp; For example</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> </FONT><FONT FACE="Courier New" SIZE="2">OAsm /omyfile test.asm</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> makes an object file called MYFILE.O</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"><B>-Ipath</B></FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> By default, OAsm will search for include paths in the current directory. If there are other paths OAsm should search for included files, this switch can be specified to have it search them.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"><B>-Ddefine = xxx</B></FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> If it is necessary to define a preprocessor definition on the command line, use this switch.&nbsp; For example:</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> </FONT><FONT FACE="Courier New" SIZE="2">OAsm /DMYINT=4 test.asm</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> defines the variable MYINT and gives it a value of 4.&nbsp;</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> A preprocessor definition doesn't have to be defined with a value:</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> </FONT><FONT FACE="Courier New" SIZE="2">OAsm /DMSDOS test.asm</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> might be used to specify preprocessing based on the program looking for the word MSDOS in #ifdef statements.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"><B>-lfile</B> listing file</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> When this switch is specified, OAsm will produce a listing file correlating the output byte stream with input lines of the file. Note the listing file is not available in preprocessor mode as no assembly is done.&nbsp;</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> By default the listing file will not show macro expansions. To get a listing file where macros are shown in expanded form, add -ml. This will also expand preprocessor repeat statements.&nbsp; Note that there is a special qualifier used in a macro definition, .nolist, which can be used on a macro-by-macro basis. When used, it prevents macros from being expanded in the listing file even when -ml is used This is useful for example to prevent cluttering the&nbsp; the listing file with expansions of often-used macros or macros that are composed largely of preprocessor statements. In fact the builtin macros that map preprocessor directives to native form all use this qualifier.
</FONT>
<BR><BR><BR>
<A NAME="hs190"></A>
<FONT FACE="Arial" COLOR="#0000FF" SIZE="5"><B>Directives</B></FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Directives are used to indicate the assembler should interpret the statement as something other than an instruction to the processor. For example they can be used to define data, or to create seperate sections for grouping code and/or data.&nbsp;</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Natively, directives are always enclosed in brackets, for example to define a byte of data:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">myvar [db 44]</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">However, the directives are redefined with default </FONT><A HREF="#hs370"><FONT FACE="Arial" SIZE="2">multiline macros</FONT></A><FONT FACE="Arial" SIZE="2">, so that the brackets are not necessary when typing code:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">myvar db 44</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">This documentation describes the macro version of the directives.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Some of the macro redefinitions of the directives are simply a mapping from the non-bracket version to the bracketized version. Other macros are more complex, adding behavior. For example the macros for psuedo-structures define the structure size, and keep track of the current section and switch back to it when the end of structure macro is encountered.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">There are several types of directives.&nbsp;</FONT><BR>

<LI><FONT FACE="Arial" SIZE="2"><A HREF="#hs199">Data Definition Directives</FONT></A><FONT FACE="Arial" SIZE="2"> define the value of a variable, either in terms of a numeric value or as a label (address) defined elsewhere in the assembler.&nbsp;</FONT>
<LI><FONT FACE="Arial" SIZE="2"><A HREF="#hs210">Data Reservation Directives</FONT></A><FONT FACE="Arial" SIZE="2"> reserve space for data, and optionally initialize that space with default values.&nbsp;</FONT>
<LI><FONT FACE="Arial" SIZE="2"><A HREF="#hs220">Label Directives</FONT></A><FONT FACE="Arial" SIZE="2"> give some attribute to a label, such as defining how it will be viewed from outside the module.&nbsp;</FONT>
<LI><FONT FACE="Arial" SIZE="2"><A HREF="#hs230">Section Directives</FONT></A><FONT FACE="Arial" SIZE="2"> group related code or data in such a way that it can be combined with other modules.&nbsp;</FONT>
<LI><FONT FACE="Arial" SIZE="2">The </FONT><A HREF="#hs240"><FONT FACE="Arial" SIZE="2">EQU Directive</FONT></A><FONT FACE="Arial" SIZE="2"> allows definition of a label in terms of a constant value.&nbsp;</FONT>
<LI><FONT FACE="Arial" SIZE="2">The </FONT><A HREF="#hs250"><FONT FACE="Arial" SIZE="2">INCBIN Directive</FONT></A><FONT FACE="Arial" SIZE="2"> allows the possibility of directly importing binary data into the current section.&nbsp;</FONT>
<LI><FONT FACE="Arial" SIZE="2">The</FONT><A HREF="#hs260"><FONT FACE="Arial" SIZE="2"> TIMES Directive</FONT></A><FONT FACE="Arial" SIZE="2"> allows a very simple form of repetitive code generation.&nbsp;</FONT>
<LI><FONT FACE="Arial" SIZE="2"><A HREF="#hs270">Psuedo-structure Directives</FONT></A><FONT FACE="Arial" SIZE="2"> allow you to define structured data in a very basic way.</FONT><BR>
<BR>
<BR>

<BR><BR><BR>
<A NAME="hs199"></A>
<FONT FACE="Arial" COLOR="#0000FF" SIZE="5"><B>Data Definition Directives</B></FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Data Definition directives define the value of a variable. There are several types of values that can be defined.&nbsp;</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">The first is a number.&nbsp; The number can sometimes be an integer, other times floating point, depending on the directive. Another type is a character or string.&nbsp; Another type of value is use of a label, or the difference between labels. Another type sometimes useful in real mode programming is a segment, which is very loosely a reference to a section. The reference can be made either by saying the section name, or using the SEG operator on a label to extract its section.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">There are five Data Definition Directives:</FONT><BR>

<LI><FONT FACE="Arial" SIZE="2">db - define byte</FONT>
<LI><FONT FACE="Arial" SIZE="2">dw - define word</FONT>
<LI><FONT FACE="Arial" SIZE="2">dd - define dword</FONT>
<LI><FONT FACE="Arial" SIZE="2">dq - define quadword</FONT>
<LI><FONT FACE="Arial" SIZE="2">dt - define tbyte</FONT><BR>
<BR>
<BR>
<FONT FACE="Arial" SIZE="2">Table 1 cross-references the various directives along with the data types can be defined with each.</FONT><BR>
<center>
<table border="1" cellpadding="2" cellspacing="2">
<tbody><BR>

    <tr>
      <td style="vertical-align: top; font-weight: bold;"></td>
      <td style="vertical-align: top; font-weight: bold;">integer</td>
      <td style="vertical-align: top; font-weight: bold;">floating point</td>
      <td style="vertical-align: top; font-weight: bold;">character/string</td>
      <td style="vertical-align: top; font-weight: bold;">label</td>
      <td style="vertical-align: top; font-weight: bold;">segment</td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top; font-weight: bold;">db</td>
      <td style="vertical-align: top;">yes</td>
      <td style="vertical-align: top;">no</td>
      <td style="vertical-align: top;">yes</td>
      <td style="vertical-align: top;">no</td>
      <td style="vertical-align: top;">no</td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top; font-weight: bold;">dw</td>
      <td style="vertical-align: top;">yes</td>
      <td style="vertical-align: top;">no</td>
      <td style="vertical-align: top;">yes</td>
      <td style="vertical-align: top;">yes</td>
      <td style="vertical-align: top;">yes</td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top; font-weight: bold;">dd</td>
      <td style="vertical-align: top;">yes</td>
      <td style="vertical-align: top;">yes</td>
      <td style="vertical-align: top;">yes</td>
      <td style="vertical-align: top;">yes</td>
      <td style="vertical-align: top;">no</td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top; font-weight: bold;">dq</td>
      <td style="vertical-align: top;">no</td>
      <td style="vertical-align: top;">yes</td>
      <td style="vertical-align: top;">no</td>
      <td style="vertical-align: top;">no</td>
      <td style="vertical-align: top;">no</td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top; font-weight: bold;">dt</td>
      <td style="vertical-align: top;">no</td>
      <td style="vertical-align: top;">yes</td>
      <td style="vertical-align: top;">no</td>
      <td style="vertical-align: top;">no</td>
      <td style="vertical-align: top;">no</td>
    </tr>
<BR>

  </tbody>
</table>
<BR>
<BR>
<FONT FACE="Arial" SIZE="2">Table 1 - directives and data types</center></FONT><BR>
<BR>
<BR>
<FONT FACE="Arial" SIZE="2">In 16-bit mode, it makes sense to use dw with labels, whereas in 32-bit mode, it makes sense to use dd with labels.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Some examples follow:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">mylab:</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> db 44</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> dw 0234h</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> dd 9999</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> dd 43.72</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> dd mylab</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> dq 19.21e17</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> dt 0.001</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Multiple values may be specified per line for these directives; for example:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">mylab:</FONT><BR>
<FONT FACE="Courier New" SIZE="2">&nbsp; db "hello world",13, 10, 0</FONT><BR>
<FONT FACE="Courier New" SIZE="2">&nbsp; dq 44.7,33,2.19.8
</FONT>
<BR><BR><BR>
<A NAME="hs210"></A>
<FONT FACE="Arial" COLOR="#0000FF" SIZE="5"><B>Data Reservation Directives</B></FONT><BR>
<BR>
<BR>
<BR>
<FONT FACE="Arial" SIZE="2">Data Reservation directives reserve space for data, and optionally give an initial value to load the space with. For example:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">resb 64</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">reserves space for 64 bytes of data. This data will default to zeros in the section it is defined it. However, an alternative form of the directive specifies an initial value. Thus:\</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">resb 64,'a'</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">fills the space with lower case 'a' values.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">There are five data reservation directives:</FONT><BR>

<LI><FONT FACE="Arial" SIZE="2">resb - reserve bytes&nbsp;&nbsp;</FONT>
<LI><FONT FACE="Arial" SIZE="2">resw - reserve words</FONT>
<LI><FONT FACE="Arial" SIZE="2">resd - reserve dwords</FONT>
<LI><FONT FACE="Arial" SIZE="2">resq - reserve quadwords</FONT>
<LI><FONT FACE="Arial" SIZE="2">rest - reserve tbytes</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">As an example:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">mylab db "hello world"</FONT><BR>
<FONT FACE="Courier New" SIZE="2">&nbsp; resb mylab + 80 - $, '.'</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">defines the string "hello world", then adds enough dots on the end to make up an 80-character buffer.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Generally, the type of data that can be defined in the optional argument to one of the Data Reservation directives is the same as for the corresponding Data Definition directive.
</FONT>
<BR><BR><BR>
<A NAME="hs220"></A>
<FONT FACE="Arial" COLOR="#0000FF" SIZE="5"><B>Label Directives</B></FONT><BR>
<BR>
<BR>
<FONT FACE="Arial" SIZE="2">Label Directives bestow some type of attribute to a label. Generally these attributes center around visibility of the label - is it visible to some entity outside the current OAsm assembly session or not?&nbsp;&nbsp;</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">For example the 'global' and 'extern' directives bestow attributes that allow the linker to resolve references to a label when the references are made in one source code file but the label is defined in a different source code file. Some of these directives require the label to be defined in the same file as the directive occurs; and others require the label to be defined elsewhere.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">The Label Directives are as follows:</FONT><BR>

<LI><FONT FACE="Arial" SIZE="2">global - the label is defined in this file, but the linker may use it to resolve references in other files</FONT>
<LI><FONT FACE="Arial" SIZE="2">extern - the label is not defined in this file, the linker should find it elsewhere</FONT>
<LI><FONT FACE="Arial" SIZE="2">export - the label is defined in this file, and will become a DLL or EXE export that Windows can use to resolve against other executables</FONT>
<LI><FONT FACE="Arial" SIZE="2">import - the label is not defined in this file, it will be imported from some other DLL or EXE file by windows</FONT><BR>
<FONT FACE="Arial" SIZE="2">&nbsp;&nbsp;</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Each use of theglobal directive can assign the 'global' attribute to one or more labels. When a label is global, it has a presence that extends beyond the current file, and the linker may resolve references to the variable to it, when those references are made in other files. Those references would typically have been made by use of the 'extern' directive. For example:</FONT><BR>
<BR>
<BR>
<FONT FACE="Courier New" SIZE="2">global puterror</FONT><BR>
<FONT FACE="Courier New" SIZE="2">puterror:</FONT><BR>
<FONT FACE="Courier New" SIZE="2">&nbsp; mov eax,errmsg</FONT><BR>
<FONT FACE="Courier New" SIZE="2">&nbsp; call strput</FONT><BR>
<FONT FACE="Courier New" SIZE="2">&nbsp; ret</FONT><BR>
<FONT FACE="Courier New" SIZE="2">errmsg:</FONT><BR>
<FONT FACE="Courier New" SIZE="2">&nbsp; db "this is an error",0</FONT><BR>
<FONT FACE="Courier New" SIZE="2">strput:</FONT><BR>
<FONT FACE="Courier New" SIZE="2">&nbsp;&nbsp; ....</FONT><BR>
<FONT FACE="Courier New" SIZE="2">&nbsp;&nbsp; ret</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">creates a function 'puterror' which is visible to other files during linkage. Global may be used with multiple labels:</FONT><BR>
<BR>
<BR>
<FONT FACE="Courier New" SIZE="2">global mylab, strput</FONT><BR>
<BR>
<BR>
<BR>
<FONT FACE="Arial" SIZE="2">Each use of the extern directive can assign the 'external' attribute to one or more labels. When a label is external, the definition is not found in the file currently being assembled. The purpose of the directive is to give the assembler and linker a hint that it should search elsewhere for the definition.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">In the above example, if 'strput' was defined in a different file from the definition of puterror you might write the following:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">global puterror</FONT><BR>
<FONT FACE="Courier New" SIZE="2">extern strput</FONT><BR>
<FONT FACE="Courier New" SIZE="2">puterror:</FONT><BR>
<FONT FACE="Courier New" SIZE="2">&nbsp; mov eax,errmsg</FONT><BR>
<FONT FACE="Courier New" SIZE="2">&nbsp; call strput</FONT><BR>
<FONT FACE="Courier New" SIZE="2">&nbsp; ret</FONT><BR>
<FONT FACE="Courier New" SIZE="2">errmsg:</FONT><BR>
<FONT FACE="Courier New" SIZE="2">&nbsp; db "this is an error",0</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">As with the global directive, extern can be used with multiple symbols:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">global puterror</FONT><BR>
<FONT FACE="Courier New" SIZE="2">extern strput, numberput</FONT><BR>
<FONT FACE="Courier New" SIZE="2">puterror:</FONT><BR>
<FONT FACE="Courier New" SIZE="2">&nbsp; push eax</FONT><BR>
<FONT FACE="Courier New" SIZE="2">&nbsp; mov eax,errmsg</FONT><BR>
<FONT FACE="Courier New" SIZE="2">&nbsp; call strput</FONT><BR>
<FONT FACE="Courier New" SIZE="2">&nbsp; pop eax</FONT><BR>
<FONT FACE="Courier New" SIZE="2">&nbsp; call numberput</FONT><BR>
<FONT FACE="Courier New" SIZE="2">&nbsp; ret</FONT><BR>
<FONT FACE="Courier New" SIZE="2">&nbsp;</FONT><BR>
<FONT FACE="Courier New" SIZE="2">errmsg db "this is error number: ",0</FONT><BR>
<BR>
<BR>
<FONT FACE="Arial" SIZE="2">The export directive defines a symbol that can be used by the windows operating system during program load. For example a DLL might use it to declare a function that is to be available to other executable files.&nbsp; Unlike the global and external directives, 'export' can only be used to change the attributes of one variable at a time. For example in the above examples adding the line:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">export puterror</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">would create an export symbol named 'puterror' which windows could then resolve to an import reference in another executable file at load time. Another form of the export directive can be used to change the visible name of the exported function:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">export puterror Error</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">would export the function puterror, but other executables would see it as being named Error.</FONT><BR>
<BR>
<BR>
<BR>
<FONT FACE="Arial" SIZE="2">The import directive is used to signify that the label is exported from some other executable or DLL file, and that windows should load that executable or DLL so that the label can</FONT><BR>
<FONT FACE="Arial" SIZE="2">be resolved. As with export there are two versions of the directive:</FONT><BR>
<BR>
<BR>
<FONT FACE="Arial" SIZE="2">i</FONT><FONT FACE="Courier New" SIZE="2">mport ExitProcess Kernel32.dll</FONT><BR>
<FONT FACE="Courier New" SIZE="2">...</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> push 0</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">&nbsp; call ExitProcess</FONT><BR>
<FONT FACE="Courier New" SIZE="2">...</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">indicates that the DLL kernel32.dll should be loaded so that a reference to the ExitProcess API call can be resolved.&nbsp;</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">It might be useful to rename ExitProcess to Quit if that is asier to remember and type:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">import ExitProcess Kernel32.dll Quit</FONT><BR>
<FONT FACE="Courier New" SIZE="2">...</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> push 0</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> call Quit&nbsp;</FONT><BR>
<FONT FACE="Courier New" SIZE="2">...</FONT><BR>

<BR><BR><BR>
<A NAME="hs230"></A>
<FONT FACE="Arial" COLOR="#0000FF" SIZE="5"><B>Section Directives</B></FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Section directives help arrange data and code. In 16-bit code they are often essential, as a section in OAsm maps more or less directly to a segment in the real-mode architecture (depending on the exact definitions given in the linker specification file); and large programs simply won't fit within a single section. The section directive would then be used to partition the various code and data into segments some way that makes sense based on the application.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">While sections aren't quite as necessary in 32-bit code, it is still customary to partition code into various sections to make it more manageable. In general, the linker will combine the code and data that is generated from assembling multiple source files so that similar types of code or data will appear close together in the output file. This is usually done based on section NAME, for example a section named CODE in one object file will be combined with sections named CODE in other object files, and similarly sections named DATA will be combined together, before the CODE and DATA sections are themselves combined together to make a part of the executable.&nbsp; Section names are generally arbitrary, however, there are some conventions made specifically in the linker specifications for windows programs.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Another use for section directives is to define absolute addresses. This is similar to using EQU to give a value to a label, but is more generic and allows use of Data Reservation directives so the assembler can calculate offsets based on the amount of data reserved. This use of section directives helps define the psuedo-struct mechanism.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">The three section directives are:</FONT><BR>
<BR>

<LI><FONT FACE="Arial" SIZE="2">section - define a named section</FONT>
<LI><FONT FACE="Arial" SIZE="2">absolute - start an absolute section</FONT>
<LI><FONT FACE="Arial" SIZE="2">align - align code or data to a specific boundary</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">The Section directive switches to a new section. If this is the first time the section is used, the section directive may also specify attributes for the section. For example:</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">section code</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">switches to a section named code. Various attributes may be specified, such as section alignment and word size of section.&nbsp; Some other attributes are parsed for compatibility with x86 assemblers, but are not currently used. The attributes are:</FONT><BR>

<LI><FONT FACE="Arial" SIZE="2">ALIGN=xxx&nbsp; - set alignment of section within EXE file</FONT>
<LI><FONT FACE="Arial" SIZE="2">CLASS=xxx - set class name. This attribute is ignored by this assembler</FONT>
<LI><FONT FACE="Arial" SIZE="2">STACK=xxx - this section is a stack section. This attribute is ignored by this assembler</FONT>
<LI><FONT FACE="Arial" SIZE="2">USE16 - this section uses 16-bit addressing modes and data</FONT>
<LI><FONT FACE="Arial" SIZE="2">USE32 - this section uses 32-bit addressing modes and data</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">As an example of a simple 32-bit program</FONT><BR>
<BR>
<BR>
<FONT FACE="Courier New" SIZE="2">section code ALIGN=2 USE32</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">extern Print</FONT><BR>
<FONT FACE="Courier New" SIZE="2">..start:</FONT><BR>
<FONT FACE="Courier New" SIZE="2">&nbsp; mov eax,helloWorld</FONT><BR>
<FONT FACE="Courier New" SIZE="2">&nbsp; call Print</FONT><BR>
<FONT FACE="Courier New" SIZE="2">&nbsp; ret</FONT><BR>
<FONT FACE="Courier New" SIZE="2">section data ALIGN=4 USE32</FONT><BR>
<FONT FACE="Courier New" SIZE="2">helloWorld db "Hello World",0</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Note that for convenience, 'segment' is defined as an alias for 'section'. So you could write:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">segment code USE32</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">to start a section named code, if you prefer.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">The absolute directive is used to switch out of sections where data can be emitted,&nbsp; into an absolute section with the specified origin. It is called absolute because these labels never get relocated by the linker; they are essentially constants. Labels defined in an absolute section will get the value of the program counter within the section, at the time the section is defined. But these labels get a constant value, that is not relocated by the linker.&nbsp; For example:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">absolute 0</FONT><BR>
<FONT FACE="Courier New" SIZE="2">lbl1:</FONT><BR>
<FONT FACE="Courier New" SIZE="2">&nbsp; resb 4</FONT><BR>
<FONT FACE="Courier New" SIZE="2">lbl2:</FONT><BR>
<FONT FACE="Courier New" SIZE="2">&nbsp; resw 3</FONT><BR>
<FONT FACE="Courier New" SIZE="2">lbl3:</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">creates an absolute section based at absolute zero, and defines three labels. These labels will have the following values based on the space that has been reserved:</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">l</FONT><FONT FACE="Courier New" SIZE="2">bl1: 0</FONT><BR>
<FONT FACE="Courier New" SIZE="2">lbl2: 4 * 1 = 4</FONT><BR>
<FONT FACE="Courier New" SIZE="2">lbl3: 4 + 3 * 2 = 10</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Note that in the definition of this section, we did not attempt to create data or code, we only reserved space. In general attempting to generate code or data in an absolute section will cause an error.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">The Align directive aligns data to a specific boundary within a section. For example:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">section data</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> db 4</FONT><BR>
<FONT FACE="Courier New" SIZE="2">align 4</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">inserts enough zeroed bytes of data to align the current section to the beginning of a four-byte boundary. Note that the section attributes still need to be set to have the same alignment or better, either in the section directive or in the linker specification file, so that the linker will honor the alignment when relocating the section.
</FONT>
<BR><BR><BR>
<A NAME="hs240"></A>
<FONT FACE="Arial" COLOR="#0000FF" SIZE="5"><B>EQU Directive</B></FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">The EQU directive allows a label to be given some value. This value must be calculable at the time the EQU directive is encountered and must resolve to a constant. However, the value itself can involve the differences between relative constructs, e.g. the difference between the current program counter and a label defined earlier in the section is a valid expression for EQU.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">When the value is a difference between relative constructs, care must be taken that the branch optimization does not change the value after it has been calculated. For more information, see the section on expressions.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">For example:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">four&nbsp; EQU 4&nbsp;&nbsp; </FONT><FONT FACE="Courier New" COLOR="#00FF00" SIZE="2">; value of the label 'four' is 4</FONT><BR>
<FONT FACE="Courier New" SIZE="2">mylab resb 64</FONT><BR>
<FONT FACE="Courier New" SIZE="2">size EQU $-mylab ; </FONT><FONT FACE="Courier New" COLOR="#00FF00" SIZE="2">program counter - mylab = 64</FONT><BR>

<BR><BR><BR>
<A NAME="hs250"></A>
<FONT FACE="Arial" COLOR="#0000FF" SIZE="5"><B>INCBIN Directive</B></FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">The Incbin directive allows the import of a binary file into the current section. For example it could be used to copy a graphics resource such as a bitmap or font verbatim into the current section. Other uses include things like importing help text from a text file, or importing a table such as a CRC table that has been pre-generated by some other program.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">The basic form of incbin is:</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">incbin "filename"</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">where filename is the name of the file to import. In this form, all data from the beginning to the end of the file will be imported. Another form starts importing at a specific offset and</FONT><BR>
<FONT FACE="Arial" SIZE="2">goes to the end:</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">incbin "Filename", 100</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">starts importing from the 100th byte in the file. Still another form lets you specify the length of data to import:</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">incbin "Filename", 96, 16</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">imports 16 bytes, starting at offset 96 within the file.</FONT><BR>

<BR><BR><BR>
<A NAME="hs260"></A>
<FONT FACE="Arial" COLOR="#0000FF" SIZE="5"><B>TIMES Directive</B></FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">The Times directive is a primitive form of repetitive programming. It takes as operands an instruction or directive, and a count of the number of times to repeat the instruction or directive. As such its functionality can often be performed more efficiently with a Data Reservation directive. It is also much more limited than the %rep group of preprocessor directives. Times is available primarily for nasm compatibility.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">For example the earlier example from the Data Reservation section could be alternatively written:</FONT><BR>
<BR>
<BR>
<FONT FACE="Courier New" SIZE="2">mylab db "hello world"</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> times mylab + 80 - $ [db '.']</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Here the native form of the db directive is used, since macro substitution is not available in this context. Times could also be used for timing:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">times 4 NOP</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">another use for times sometimes found in NASM programs is to align data:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">times ($$-$)%4 [db 0]</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">but in this assembler it is better to use the align directive.
</FONT>
<BR><BR><BR>
<A NAME="hs270"></A>
<FONT FACE="Arial" COLOR="#0000FF" SIZE="5"><B>Psuedo-structure Directives</B></FONT><BR>
<BR>
<BR>
<FONT FACE="Arial" SIZE="2">Structures aren't really a construct supported by the assembler, however, clever macro definitions allow definition of structure-like entities. For example, consider the following:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">struc</FONT><BR>
<FONT FACE="Courier New" SIZE="2">astruc</FONT><BR>
<FONT FACE="Courier New" SIZE="2">s1 resb 4</FONT><BR>
<FONT FACE="Courier New" SIZE="2">s2 resw 3</FONT><BR>
<FONT FACE="Courier New" SIZE="2">s3 resd 5</FONT><BR>
<FONT FACE="Courier New" SIZE="2">s4 resb 1</FONT><BR>
<FONT FACE="Courier New" SIZE="2">endstruc</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">This defines the following label values similar to how they were defined in an absolute section:</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">s1: 0</FONT><BR>
<FONT FACE="Arial" SIZE="2">s2: 4 * 1 = 4</FONT><BR>
<FONT FACE="Arial" SIZE="2">s3: 4 + 3 * 2= 10</FONT><BR>
<FONT FACE="Arial" SIZE="2">s4: 10 + 5 *4 = 30</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">The structure mechanism also defines astruc as 0, and it defines the size of the struct 'astruc_size' as 30 + 1 = 31.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">To access the member of a structure one might use something like:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">mov eax,[ebx + s3]</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">The structure mechanism could just as well be done with absolute sections or EQU statements (except that a side effect of the structure mechanism is to define a size). But a little more more interestingly, if you introduce local labels and remember that a local label can be accessed from anywhere if its fully qualified name is specified you might write:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">struct astruc</FONT><BR>
<FONT FACE="Courier New" SIZE="2">.s1 resb 4</FONT><BR>
<FONT FACE="Courier New" SIZE="2">.s2 resw 3</FONT><BR>
<FONT FACE="Courier New" SIZE="2">.s3 resd 5</FONT><BR>
<FONT FACE="Courier New" SIZE="2">.s4 resb 1</FONT><BR>
<FONT FACE="Courier New" SIZE="2">endstruc</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">This lets you qualify the name and use:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">mov eax,[ebx + astruc.s3]</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">However you need to be careful with this. Structures aren't really part of the assembler, but are instead an extension provided by built-in macros. So you can't make an instance of a structure and then use a period to qualify the instance name with a structure member. For example:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">mystruc resb astruc_size,0</FONT><BR>
<FONT FACE="Courier New" SIZE="2">mov&nbsp; eax,[mystruc.s3]</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">is not valid, because the label 'mystruc.s3' does not exist. The move would have to be changed to something like:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">mov eax,[mystruc + astruc.s3]
</FONT>
<BR><BR><BR>
<A NAME="hs280"></A>
<FONT FACE="Arial" COLOR="#0000FF" SIZE="5"><B>Labels</B></FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Labels may begin with any alphabetic character, or with any of the characters '_', '?', or '.'. Within a label, alphabetic characters, digits, or any of the characters '_', '$', '#', '@', '~', '?', '.' may occur.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Labels may be followed by a ':' character, but this is optional.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">There are various types of labels. A standard label begins with an alphabetic character, or '_', '?'.&nbsp;</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Additionally 'local' labels may be defined. Local labels always start with a '.'. Local labels may be reused, providing there is a standard label between uses. This allows you to use meaningless names like '.1' '.2' and so forth within a local context, instead of having to come up with</FONT><BR>
<FONT FACE="Arial" SIZE="2">unique labels every time a label is required.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">For example in the fragment</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">routine1:</FONT><BR>
<FONT FACE="Courier New" SIZE="2">&nbsp; test ax,1</FONT><BR>
<FONT FACE="Courier New" SIZE="2">&nbsp; jnz .exit ;&nbsp;</FONT><BR>
<FONT FACE="Courier New" SIZE="2">&nbsp; </FONT><FONT FACE="Courier New" COLOR="#00FF00" SIZE="2">///do something</FONT><BR>
<FONT FACE="Courier New" SIZE="2">.exit:</FONT><BR>
<FONT FACE="Courier New" SIZE="2">&nbsp; ret</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">routine2:</FONT><BR>
<FONT FACE="Courier New" SIZE="2">&nbsp; cmp bx,ax</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">&nbsp; jc .exit</FONT><BR>
<FONT FACE="Courier New" SIZE="2">&nbsp; </FONT><FONT FACE="Courier New" COLOR="#00FF00" SIZE="2">; do something</FONT><BR>
<FONT FACE="Courier New" SIZE="2">.exit:</FONT><BR>
<FONT FACE="Courier New" SIZE="2">clc</FONT><BR>
<FONT FACE="Courier New" SIZE="2">ret</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">.exit is defined twice, however, each definition follows a different standard label so the two definitions are actually different labels.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Internally, each use of a local label does have a unique name, made up by concatenating the most recent standard label name with the local label name. In the above example the internal names of the two labels are thus routine1.exit and routine2.exit.&nbsp; It is possible to branch to the fully qualified name from within another context.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">The context for local labels changes each time a new standard label is defined. It is sometimes desirable to define a kind of label which is neither a standard label, that would change the local label context, or a local label, which is useful only within that&nbsp; context. This is done by prepending the label name with '..@'. For example in the below:</FONT><BR>
<BR>
<BR>
<FONT FACE="Courier New" SIZE="2">routine3:</FONT><BR>
<FONT FACE="Courier New" SIZE="2">&nbsp; text ax,1</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">&nbsp; jnz .exit</FONT><BR>
<FONT FACE="Courier New" SIZE="2">&nbsp; ..@go3:</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> ; do something</FONT><BR>
<FONT FACE="Courier New" SIZE="2">.exit:</FONT><BR>
<FONT FACE="Courier New" SIZE="2">ret</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">main:</FONT><BR>
<FONT FACE="Courier New" SIZE="2">&nbsp; call ..@go3</FONT><BR>
<FONT FACE="Courier New" SIZE="2">&nbsp; ret</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">the label ..@go3 is accessible from anywhere, but it is not qualified by the local label context of routine 3, nor does it start a new local label context, so .exit is</FONT><BR>
<FONT FACE="Arial" SIZE="2">still a local label within the context of routine3.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">OAsm generates two forms of such labels&nbsp; - one within macro invocations, and within 'contexts' as shown in other sections. In these cases the label starts with '..@', has a sequence of digits, then has a '.' or '@' character followed by user-specified text. When using the nonlocal label format, these forms should be avoided to avoid clashing with assembler-generated labels.</FONT><BR>
<BR>
<BR>
<FONT FACE="Arial" SIZE="2">OAsm defines one special label, '..start'. This label, if used, indicates that this particular position in the code space is the first code that should be executed when the program runs.&nbsp; Note that if two modules both declare this label and are linked together, the linker will throw an error.
</FONT>
<BR><BR><BR>
<A NAME="hs290"></A>
<FONT FACE="Arial" COLOR="#0000FF" SIZE="5"><B>Numbers and Expressions</B></FONT><BR>
<BR>
<BR>
<FONT FACE="Arial" SIZE="2">Integers may be specified in base 8, base 10, or base 16. The rules for specifying integers follow the C language standard; e.g. if a number starts with 0 it is assumed to be base 8; if it starts with 0x&nbsp; it is assumed to be base 16; otherwise it is base 10. For compatibility with other assemblers OAsm also supports the trailing 'h' to indicate hexadecimal values (base 16) but such numbers must start with a digit to prevent them from being interpreted as labels.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">For example:</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">012 ; octal for the decimal value 10</FONT><BR>
<FONT FACE="Arial" SIZE="2">12 ; the decimal value 12</FONT><BR>
<FONT FACE="Arial" SIZE="2">0x12 ; hexadecimal for the decimal value 18</FONT><BR>
<FONT FACE="Arial" SIZE="2">012h ; hexadecimal for the decimal value 18</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Floating point values are specified similarly as to a C compiler.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">For example:</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">1.03</FONT><BR>
<FONT FACE="Arial" SIZE="2">17.93e27</FONT><BR>
<FONT FACE="Arial" SIZE="2">10000.4e-27</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Note that floating point values must start with a digit in&nbsp; OAsm. .003 is not a valid floating point value because character sequences starting</FONT><BR>
<FONT FACE="Arial" SIZE="2">with a dot are interpreted as local labels.&nbsp; Use 0.003 instead.</FONT><BR>
<BR>
<BR>
<FONT FACE="Arial" SIZE="2">OAsm makes no real distinction between single characters and sequences of characters. Single quotes (') and double quotes (") may be used interchangeably. But the interpretation of characters and strings depends on context.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">When used in an instruction:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">mov ax,"TO"</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">The operand will be constructed in such a way that storing it to memory will result in the characters being stored in the same order they were typed.</FONT><BR>
<FONT FACE="Arial" SIZE="2">In other words, the sequence:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">mov ax,"TO"</FONT><BR>
<FONT FACE="Courier New" SIZE="2">mov [label],ax</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">will result in the value at label being the same as if the assembler directive db were used to initialize the value:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">label db "TO"</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Characters at the end of a string that cannot be encoded in the instruction will be lost, thus:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">mov ax,"hi roger"</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">is the same as:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">mov ax,"hi"</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">because the register ax only holds the equivalent of two characters.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">On the other hand, data areas may be initialized with strings with various directives. There are three types of values that can be initialized this way; bytes (1byte), words(2 bytes), and double-words(4 bytes). For ASCII characters, the encoding is just the character, with enough leading zeros to pad to the appropriate size.</FONT><BR>
<BR>
<BR>
<FONT FACE="Arial" SIZE="2">The symbol '$', by itself, means the current program counter. This is an absolute program counter, and if passed through to the linker will result in an absolute offset being compiled into the program. But sometimes it doesn't need to be used as an absolute value, for example it can be used to find the length of a section of data:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">mylabel db "hello world",10,13</FONT><BR>
<FONT FACE="Courier New" SIZE="2">hellosize EQU $-mylabel</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">where the EQU statement assigns the value of the expression '$-mylabel' to the label hellosize.&nbsp;&nbsp;</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">The symbol '$$' means the beginning of the current section. For example the expression $-$$ gives the offset into the current section.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">A more complex expression may usually be used wherever a number may be specified, consisting perhaps of numbers, labels, special symbols, and operators. OAsm uses operators similar to the ones found in a C compiler, with precedence similar to the C compiler, and introduces some new operators as well. See table 1 for a listing of operators, and table 2 for a listing of operator precedences.</FONT><BR>
<center>
<table border="1" cellpadding="2" cellspacing="2">
  <tbody>
<BR>

    <tr>
      <td style="vertical-align: top;">( )</td>
      <td style="vertical-align: top;">specify evaluation order ofsub-expressions</td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top;">SEG</td>
      <td style="vertical-align: top;">refers to segment of a variable (16-bit only)</td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top;">-</td>
      <td style="vertical-align: top;">unary minus</td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top;">+</td>
      <td style="vertical-align: top;">unary plus</td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top;">~</td>
      <td style="vertical-align: top;">bitwise complement</td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top;">!</td>
      <td style="vertical-align: top;">logical not</td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top;">*</td>
      <td style="vertical-align: top;">multiply</td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top;">/</td>
      <td style="vertical-align: top;">divide, unsigned</td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top;">/-</td>
      <td style="vertical-align: top;">divide, signed</td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top;">%</td>
      <td style="vertical-align: top;">modulous, unsigned</td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top;">%-</td>
      <td style="vertical-align: top;">modulous, signed</td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top;">+</td>
      <td style="vertical-align: top;">addition</td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top;">-</td>
      <td style="vertical-align: top;">subtraction</td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top;">WRT</td>
      <td style="vertical-align: top;">offset of a variable, from a specific segment</td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top;">&gt;&gt;</td>
      <td style="vertical-align: top;">unsigned shift right</td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top;">&lt;&lt;</td>
      <td style="vertical-align: top;">unsigned shift left</td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top;">&gt</td>
      <td style="vertical-align: top;">greater than</td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top;">&gt;=</td>
      <td style="vertical-align: top;">greater than or equal</td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top;">&lt;</td>
      <td style="vertical-align: top;">less than
</td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top;">&lt;=</td>
      <td style="vertical-align: top;">less than or equal</td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top;">==</td>
      <td style="vertical-align: top;">equals</td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top;">!=</td>
      <td style="vertical-align: top;">not equal to</td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top;">&amp;</td>
      <td style="vertical-align: top;">binary and</td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top;">^</td>
      <td style="vertical-align: top;">binary exclusive or</td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top;">|</td>
      <td style="vertical-align: top;">binary or</td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top;">&amp;&amp;</td>
      <td style="vertical-align: top;">logical and</td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top;">||</td>
      <td style="vertical-align: top;">logical or</td>
    </tr>
<BR>

  </tbody>
</table>
<BR>
<BR>
<FONT FACE="Arial" SIZE="2">Table 1, Operator meanings</FONT><BR>

<table border="1" cellpadding="2" cellspacing="2">
  <tbody>
<BR>

    <tr>
      <td style="vertical-align: top;">( )</td>
      <td style="vertical-align: top;">parenthesis</td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top;">SEG, -, +, ~, !</td>
      <td style="vertical-align: top;">unary operators</td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top;">*, /, /-, %, %-</td>
      <td style="vertical-align: top;">multiplicative operators</td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top;">+, -, WRT</td>
      <td style="vertical-align: top;">additive operators</td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top;">&lt;&lt,&gt;&gt;</td>
      <td style="vertical-align: top;">shift operators</td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top;">&gtl, &gt;=, &lt;, &lt;=</td>
      <td style="vertical-align: top;">inequality operators</td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top;">==, !=</td>
      <td style="vertical-align: top;">equality operators</td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top;">&amp;</td>
      <td style="vertical-align: top;">bitwise and</td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top;">^</td>
      <td style="vertical-align: top;">bitwise exclusive or</td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top;">|</td>
      <td style="vertical-align: top;">bitwise or</td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top;">&amp;&amp;</td>
      <td style="vertical-align: top;">logical and</td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top;">||</td>
      <td style="vertical-align: top;">logical or</td>
    </tr>
<BR>

  </tbody>
</table>
<BR>
<BR>
<FONT FACE="Arial" SIZE="2">Table 2, Operator precedence from highest to lowest</FONT><BR>
<BR>
</center>
<BR>
<BR>
<BR>
<FONT FACE="Arial" SIZE="2">Expressions involving labels or segments will often be pushed off to the linker for evaluation, however, the linker only knows simple math such as +-*/ and SEG. Sometimes however, an expression such as '$-mylab' can be directly evaluated by the assembler, provided mylab is defined earlier in the current segment. Such evaluations would result in a constant being passed</FONT><BR>
<FONT FACE="Arial" SIZE="2">to the linker.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Note that OAsm mimics a multipass assembler, and will attempt to optimize branches to the smallest available form. This is normally not a problem as after each optimization pass OAsm will reevaluate expressions found in the code or data. However, some assembler directives such as EQU and TIMES evaluate their operands immediately, when the instruction is encountered. And all branches start out at the largest possible size. That means that a sequence like:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">section code</FONT><BR>
<FONT FACE="Courier New" SIZE="2">USE32</FONT><BR>
<FONT FACE="Courier New" SIZE="2">label:</FONT><BR>
<FONT FACE="Courier New" SIZE="2">&nbsp; cmp eax,1</FONT><BR>
<FONT FACE="Courier New" SIZE="2">&nbsp; jz forward</FONT><BR>
<FONT FACE="Courier New" SIZE="2">&nbsp; inc eax</FONT><BR>
<FONT FACE="Courier New" SIZE="2">forward:</FONT><BR>
<FONT FACE="Courier New" SIZE="2">size EQU forward - label</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">will result in 'size' being evaluated with the jz being a 6-byte instruction, but the final code will have the jz being a two-byte instruction. This disparity between the calculated value and the</FONT><BR>
<FONT FACE="Arial" SIZE="2">actual value can introduce subtle bugs in a program. To get around this explicitly clarify any jumps in a region that is going to be sized with 'short' or 'near':</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">label:</FONT><BR>
<FONT FACE="Courier New" SIZE="2">&nbsp; cmp eax,1</FONT><BR>
<FONT FACE="Courier New" SIZE="2">&nbsp; jz short forward</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">&nbsp; inc eax</FONT><BR>
<FONT FACE="Courier New" SIZE="2">forward:</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Data directives aren't subject to size optimizations, so in the usual case of taking the size of a data region this isn't an issue.
</FONT>
<BR><BR><BR>
<A NAME="hs300"></A>
<FONT FACE="Arial" COLOR="#0000FF" SIZE="5"><B>Preprocessor Directives</B></FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">The OAsm preprocessor is a C preprocessor, with extensions. The preprocessor can be considered to be a set of routines which go through the code before it is assembled, making certain types of textual transformations to the source code. The transformations range from simple substitution of text or lines of text when a keyword is encountered, to inclusion of text from another file, to selectively ignoring some lines based on compile-time settings. The main difference from a C preprocessor, other than the extensions, is that instead of starting a preprocessor directive with a hash ('#') preprocessor directives are started with a percent ('%').</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Many of these directives involve </FONT><A HREF="#hs330"><FONT FACE="Arial" SIZE="2">Conditional Processing</FONT></A><FONT FACE="Arial" SIZE="2">, which is a way to selectively choose what lines of code to assemble and what lines to ignore based on previous declarations.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Table 1 shows the </FONT><A HREF="#hs310"><FONT FACE="Arial" SIZE="2">C-style preprocessor directives</FONT></A><FONT FACE="Arial" SIZE="2">. These directives are compatible with similar directives in a C Compiler's preprocessor.</FONT><BR>
 <center>
<table border="1" cellpadding="2" cellspacing="2">
  <tbody>
<BR>

    <tr>
      <td style="vertical-align: top;">%define</td>
      <td style="vertical-align: top;">define a constant or function-style macro</td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top;">%undef</td>
      <td style="vertical-align: top;">undefine a macro</td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top;">%error</td>
      <td style="vertical-align: top;">display an error</td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top;">%line</td>
      <td style="vertical-align: top;">set the file and line displayed in error messages</td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top;">%include</td>
      <td style="vertical-align: top;">include another file</td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top;">%if</td>
      <td style="vertical-align: top;">conditional which tests fornonzero expression</td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top;">%elif</td>
      <td style="vertical-align: top;">else-style conditional which tests for nonzero-expression</td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top;">%ifdef</td>
      <td style="vertical-align: top;">conditional which tests to see if a macro has been %defined</td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top;">%ifndef</td>
      <td style="vertical-align: top;">conditional which tests to see if a macro has not been %defined</td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top;">%else</td>
      <td style="vertical-align: top;">else clause for conditionals</td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top;">%endif</td>
      <td style="vertical-align: top;">end of conditional</td>
    </tr>
<BR>

  </tbody>
</table>
<BR>
<BR>
<FONT FACE="Arial" SIZE="2">Table 1 - C lanuage style preprocessor directives</center>
</FONT><BR>
<BR>
<BR>
<FONT FACE="Arial" SIZE="2">Table 2 shows </FONT><A HREF="#hs320"><FONT FACE="Arial" SIZE="2">basic extensions to the C preprocessor</FONT></A><FONT FACE="Arial" SIZE="2"> that are similar to directives already found in the preprocessor. This includes a new directive %assign which is like %define except it evaluates the macro value based on the assumption it is a numeric expression. It also includes case insensitive macro definition directives, and the beginning of an extensive set of extensions to condtionals that are similar to the %elif&nbsp; mechanism.</FONT><BR>
<center>
<table border="1" cellpadding="2" cellspacing="2">
  <tbody>
<BR>

    <tr>
      <td>%assign</td>
      <td style="vertical-align: top;">Like %define, but evaluates an expression and sets the value to the result</td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top;">%iassign </td>
      <td style="vertical-align: top;">%assign with a case-insensitive name</td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top;">%idefine</td>
      <td style="vertical-align: top;">%define with a case-insensitive name</td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top;">%elifdef</td>
      <td style="vertical-align: top;">else-style conditional which tests to see if a macro has been %defined</td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top;">%elifndef</td>
      <td style="vertical-align: top;">else-style conditional which tests to see if a macro has not been %defined</td>
    </tr>
<BR>

  </tbody>
</table>
<BR>
<BR>
<FONT FACE="Arial" SIZE="2">Table 2 - Basic extensions to C style preprocessor</center>
</FONT><BR>
<BR>
<BR>
<FONT FACE="Arial" SIZE="2">Table 3 shows extensions to the conditional mechanism that allow </FONT><A HREF="#hs340"><FONT FACE="Arial" SIZE="2">text comparisons</FONT></A><FONT FACE="Arial" SIZE="2">. There are both case sensitive and case insensitive forms of these directives.</FONT><BR>
<BR>
 <center>
<table border="1" cellpadding="2" cellspacing="2">
  <tbody>
<BR>

    <tr>
      <td style="vertical-align: top;">%ifidn</td>
      <td style="vertical-align: top;">Case sensitive test for string matching</td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top;">%ifnidn</td>
      <td style="vertical-align: top;">Case sensitive test for string not matching</td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top;">%elifidn</td>
      <td style="vertical-align: top;">else-style case sensitive test for string matching</td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top;">%elifnidn</td>
      <td style="vertical-align: top;">else-style case sensitive test for string not matching</td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top;">%ifidni</td>
      <td style="vertical-align: top;">Case insensitive test for string matching</td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top;">%ifnidni</td>
      <td style="vertical-align: top;">Case insensitive test for string
not matching</td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top;">%elifndi</td>
      <td style="vertical-align: top;">else-style case insensitive test
for string matching</td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top;">%elifnidni</td>
      <td style="vertical-align: top;">else-style case insensitive test
for string not matching</td>
    </tr>
<BR>

  </tbody>
</table>
<BR>
<BR>
<FONT FACE="Arial" SIZE="2">Table 3 - Text Comparison Conditionals</center>
</FONT><BR>
<BR>
<BR>
<FONT FACE="Arial" SIZE="2">Table 4 shows various extensions to the conditional mechanism that allow </FONT><A HREF="#hs350"><FONT FACE="Arial" SIZE="2">classification of a token's type</FONT></A><FONT FACE="Arial" SIZE="2">. They can be used for example in </FONT><A HREF="#hs370"><FONT FACE="Arial" SIZE="2">multiline macros</FONT></A><FONT FACE="Arial" SIZE="2">, to allow a single macro to have different behaviors based on the type of a macro argument.</FONT><BR>
<BR>
<BR>
<center>
<table border="1" cellpadding="2" cellspacing="2">
  <tbody>
<BR>

    <tr>
      <td>%ifid</td>
      <td style="vertical-align: top;">test to see if argument is an
identifier</td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top;">%ifnid</td>
      <td style="vertical-align: top;">test to see if argument is not
an identifier</td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top;">%elifid</td>
      <td style="vertical-align: top;">else-style test to see if
argument is an identifier</td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top;">%elifnid</td>
      <td style="vertical-align: top;">else-style test to see if
argument is not an identifier</td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top;">%ifnum</td>
      <td style="vertical-align: top;">test to see if argument is a
number</td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top;">%ifnnum</td>
      <td style="vertical-align: top;">test to see if argument is not a
number</td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top;">%elifnum</td>
      <td style="vertical-align: top;">else-style test to see if
argument is a number</td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top;">%elifnnum</td>
      <td style="vertical-align: top;">else-style test to see if
argument is not a number</td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top;">%ifstr</td>
      <td style="vertical-align: top;">test to see if argument is a
string</td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top;">%ifnstr</td>
      <td style="vertical-align: top;">test to see if argument is not a
string</td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top;">%elifstr</td>
      <td style="vertical-align: top;">else-style test to see if
argument is a string</td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top;">%elifnstr</td>
      <td style="vertical-align: top;">else-style test to see if
argument is not a string</td>
    </tr>
<BR>

  </tbody>
</table>
<BR>
<BR>
<FONT FACE="Arial" SIZE="2">Table 4 - Token Type Classification Conditionals</center>
</FONT><BR>
<BR>
<BR>
<FONT FACE="Arial" SIZE="2">Table 5 shows the </FONT><A HREF="#hs370"><FONT FACE="Arial" SIZE="2">Multiline Macro Extensions</FONT></A><FONT FACE="Arial" SIZE="2"> and the </FONT><A HREF="#hs380"><FONT FACE="Arial" SIZE="2">Repeat Block Extensions</FONT></A><FONT FACE="Arial" COLOR="#800000" SIZE="2"> </FONT><FONT FACE="Arial" SIZE="2">. These extentions include multiline macros, as well as a powerful facility for using the preprocessor to repeat sections of code or data.</FONT><BR>
<BR>
<center>
<table border="1" cellpadding="2" cellspacing="2">
  <tbody>
<BR>

    <tr>
      <td style="vertical-align: top;">%macro</td>
      <td style="vertical-align: top;">start a multiline macro</td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top;">%imacro</td>
      <td style="vertical-align: top;">start a multiline macro, caseinsensitive name
</td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top;">%endmacro </td>
      <td style="vertical-align: top;">end a multiline macro</td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top;">%rotate</td>
      <td style="vertical-align: top;">rotate arguments in a multiline macro</td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top;">%rep </td>
      <td style="vertical-align: top;">start a repeat block </td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top;">%endrep </td>
      <td style="vertical-align: top;">end a repeat block </td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top;">%exitrep</td>
      <td style="vertical-align: top;">exit a repeat block prematurely</td>
    </tr>
<BR>

  </tbody>
</table>
<BR>
<BR>
<FONT FACE="Arial" SIZE="2">Table 5 - Multiline Macro and Repeat Block Extensions</center>
</FONT><BR>
<BR>
<BR>
<FONT FACE="Arial" SIZE="2">Table 6 shows the </FONT><A HREF="#hs360"><FONT FACE="Arial" SIZE="2">Context-Related Extensions</FONT></A><FONT FACE="Arial" SIZE="2">.&nbsp; Preprocessor contexts are a powerful mechanism that can be used to 'remember' data between successive macro invocations, and for example could be used to construct a high-level representation of control constructs in the assembler.</FONT><BR>
<center>
<table border="1" cellpadding="2" cellspacing="2">
  <tbody>
<BR>

    <tr>
      <td style="vertical-align: top;">%push</td>
      <td style="vertical-align: top;">start a new context</td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top;">%pop</td>
      <td style="vertical-align: top;">end a new context</td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top;">%repl</td>
      <td style="vertical-align: top;">rename the context at the topeof the context stack
</td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top;">%ifctx</td>
      <td style="vertical-align: top;">test to see if a context is in effect</td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top;">%ifnctx</td>
      <td style="vertical-align: top;">test to see if a context is not in effect</td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top;">%elifctx</td>
      <td style="vertical-align: top;">else-style test to see if a context is in effect</td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top;">%elifnctx</td>
      <td style="vertical-align: top;">else-style test to see if a context is not in effect</td>
    </tr>
<BR>

  </tbody>
</table>
<BR>
<BR>
<FONT FACE="Arial" SIZE="2">Table 6 - Context - Related Extensions</center>
</FONT><BR>

<BR><BR><BR>
<A NAME="hs310"></A>
<FONT FACE="Arial" COLOR="#0000FF" SIZE="5"><B>C-Style Preprocessor directives</B></FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">The C-Style preprocessor directives are compatible with similar directives that are existant in preprocessors for C compilers.&nbsp; OAsm does not change the behavior of these directives other than to change the initial character which introduces the directive from '#' to '%'.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"><B>%define</B></FONT><BR>
<FONT FACE="Arial" SIZE="2"> %define introduces a method to perform textual substitutions. In its simplest form it will just replace an identifier with some text:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> %define HELLO_WORLD "Hello World"</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> replaces all instances of the identifier HELLO_WORLD with the indicated string. For example after this definition the following statement:</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> </FONT><FONT FACE="Courier New" SIZE="2">db HELLO_WORLD</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> will result in the string "Hello World" being compiled into the program.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> %define is not limited to giving names to strings, it will do any sort of text substitution you want. That could include defining names for constants, or giving a name to an often-used instruction, for example.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> In the below:</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> </FONT><FONT FACE="Courier New" SIZE="2">%define ARRAY_MAX 4</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> mov eax,ARRAY_MAX</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> the text "4" gets substituted for ARRAY_MAX prior to assembling the mov instruction, so what the assembler sees is:</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> </FONT><FONT FACE="Courier New" SIZE="2">mov eax,4</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> Note that definitions are also processed for substitution:</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> </FONT><FONT FACE="Courier New" SIZE="2">%define ONE 1</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> %define TWO (ONE + 1)</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> %define THREE (TWO + 1)</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> mov eax,THREE</FONT><BR>
<FONT FACE="Arial" SIZE="2">&nbsp;</FONT><BR>
<FONT FACE="Arial" SIZE="2"> is substituted multiple times during processing, with the final result being:</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> </FONT><FONT FACE="Courier New" SIZE="2">mov eax,((1 +1) + 1)</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> OAsm will detect recursive substitutions and halt the substitution process, so things like:</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> </FONT><FONT FACE="Courier New" SIZE="2">%define ONE TWO</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> %define TWO ONE</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> will halt after detecting the recursion.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> Also, the substitution text can be empty:</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> </FONT><FONT FACE="Courier New" SIZE="2">%define EMPTY</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> mov eax, EMPTY</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> results in the translated text:</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> </FONT><FONT FACE="Courier New" SIZE="2">mov eax,</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> which cannot be assembled and will result in a syntax error during assembly.</FONT><BR>
<BR>
<BR>
<FONT FACE="Arial" SIZE="2"> %define can also be used in its functional form for more advanced text replacement activities. In this form, the identifier is parameterized. During substitutions, arguments are also specified; and the original parameters are replaced with the arguments while substitution is occurring. For example:</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> </FONT><FONT FACE="Courier New" SIZE="2">%define mul(a,b) a * b</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> mov eax,mul(4,7)</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> mov eax,4 * 7</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> prior to assembly. It is usually not a good idea to write this quite the way it was done however. The user may elect to put any text they want in the invocation, so one thing that can happen is they write:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> mov eax, mul(4+3, 7+2)</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> This gets translated to:</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> </FONT><FONT FACE="Courier New" SIZE="2">mov eax, 4 + 3 * 7 + 2</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> which was probably not the intent. Below is what was probably desired:</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> </FONT><FONT FACE="Courier New" SIZE="2">mov eax, (4+3) * (7+2)</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> For this reason it is a good idea to fully parenthesize the parameters used in the original definition:</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> </FONT><FONT FACE="Courier New" SIZE="2">%define mul(a,b) ((a) * (b))</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> mov eax, mul(4+3, 7+2)</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> becomes</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> mov eax, ((4 + 3) * (7 + 2))</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> The extra set of parenthesis is used to prevent similar situations from happening when 'mul' is used as a subexpression of another expression.</FONT><BR>
<BR>
<BR>
<FONT FACE="Arial" SIZE="2"> Note that when using %define, substituted text is not evaluated in any way, other than to process substitutions on the identifier and any specified parameters. So the move statement in the last example would be visible to the assembler exactly as the substitutions dictate, and the assembler has to do further evaluation of the expression if it wants a constant value.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> Within a definition, there are a couple of special-case substitutions that can occur with function-style definitions. In Stringizing, a parameter can be turned into a string. For example if you write:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> %define STRINGIZE(str) #str</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> db STRINGIZE(Hello World)</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> quotes will be placed around the substituted parameter. So this translates to:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> db "Hello World"</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> prior to assembly.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> In Tokenizing, new identifiers may be produced. For example:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> %define Tokenizing(prefix, postfix) (prefix ## postfix + 4)</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> mov eax,Tokenizing(Hello,World)</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> would be translated to:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> mov eax,HelloWorld + 4</FONT><BR>
<FONT FACE="Arial" SIZE="2">&nbsp;</FONT><BR>
<FONT FACE="Arial" SIZE="2"> prior to assembly.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> Note that even though the hash character used to start a preprocessor statement has been changed to '%', hash is still used in stringizing and tokenizing.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> Finally, OAsm supports the C99 extension to function-style definitions, which allows variable-length argument lists. For example:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> %define mylist(first, ...) dw first, __VA_ARGS__</FONT><BR>
<FONT FACE="Arial" SIZE="2">&nbsp;</FONT><BR>
<FONT FACE="Arial" SIZE="2"> where __VA_ARGS__ means append all remaining arguments that are specified, could be used like this:</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> </FONT><FONT FACE="Courier New" SIZE="2">mylist(1)</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> mylist(1,2)</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> mylist(1,2,3,4,5)</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> and so on. These would expand to:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> dw 1</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> dw 1,2</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> dw 1,2,3,4,5</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> Note that the name of the identifier that is replaced is case-sensitive with %define, for example HELLO_WORLD is not the same as Hello_World. There is a case-insensitive form of this directive %idefine which can be used to make these and other related identifiers the same.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> Note: OAsm does not support overloading function-style macros.&nbsp;</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> For convenience OAsm allows %define definitions on the command line, which are useful for tailoring build behavior either directly or through the conditional processing facility.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"><B>%undef</B></FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> %undef undoes a previous definition, so that it will not be considered for further substitutions (unless defined again). For example:</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> %define REG_EBX 3</FONT><BR>
<FONT FACE="Arial" SIZE="2"> %undef REG_EBX</FONT><BR>
<FONT FACE="Arial" SIZE="2"> mov eax, REG_EBX</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> results in no substitution occurring for the use of REG_EBX.&nbsp; In this case this will result in an error.&nbsp;&nbsp;</FONT><BR>
<BR>
<BR>
<FONT FACE="Arial" SIZE="2"><B>%error</B></FONT><BR>
<FONT FACE="Arial" SIZE="2"> %error displays an error, causing the assembler to not generate code. For example:</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> </FONT><FONT FACE="Courier New" SIZE="2">%error my new error</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> might display something like:</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"><B> Error errdemo.asm(1): Error Directive: my new error</B></FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> When the file is assembled.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"><B>%line</B></FONT><BR>
<FONT FACE="Arial" SIZE="2"> %line is used to change the file and line number listed in the error reporting. By default the error reporting indicates the file and line an error occur on.&nbsp; Sometimes in generated source code files, it is useful to refer to the line number in the original source code rather than in the file that is currently being assembled. %line accomplishes this by updating internal tables to indicate to the preprocessor that it should use alternate information when reporting an error. For example inserting the following at line 443 of test.asm:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> mov eax,^4</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> produces a syntax error when the code is assembled:</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"><B> Error test.asm(443): Syntax Error</B></FONT><BR>
<FONT FACE="Arial" SIZE="2"><B>&nbsp;</B></FONT><BR>
<FONT FACE="Arial" SIZE="2"> If an additional %line directive is inserted:</FONT><BR>
<FONT FACE="Arial" SIZE="2">&nbsp;</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> %line 10, "demo.c"</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> mov eax,^4</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> the error changes to:</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"><B> Error demo.c(10): Syntax Error</B></FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> Note that once %line is used to change the line number and file name, OAsm remembers the new information and continues to increment the new line number each time it processes a line of source code.</FONT><BR>
<BR>
<BR>
<FONT FACE="Arial" SIZE="2">%include</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> %include is used to start the interpretation of another source file. The current source file is suspended, and the new source file is loaded and assembled. Once the assembler is done with the new source file (and anything it also %includes)&nbsp; assembly resumes beginning where it left off in the current source file.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> This facility is useful for example to hold preprocessor constants and structures that are shared between multiple source files. But the included file can include any valid assembler statement, including GLOBAL and EXTERN definitions.&nbsp;</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> For example if test.asm is being assembled and the statement:</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> %include "test1.asm"</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> is encountered, the assembly of test.asm will temporarily be suspended while OAsm goes off to assemble test1.asm.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> After it is done with test1.asm,&nbsp; OAsm remembers that it was previously assembling test.asm and picks up in that file where it left off (e.g. at the line after the %include statement).</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> This is not quite the same as specifying both test.asm and test1.asm on the command line.&nbsp; In the current example there is only one output file which contains the contents of both test.asm and test1.asm, where as if both were specified on the command line they would result in separate output files.&nbsp; Additionally, doing it this way can allow the two files to depend on one another in a way that couldn't happen if they were compiled separately.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> For convenience, an include path may be specified on the command line, and OAsm will search for included files both in the current directory, and in directories specified on that path.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"><B>%if</B></FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> %if is a %if-style conditional that takes a numeric expression as an argument. If the numeric expression evaluates to a non-zero value, the result of the evaluation will be true, otherwise it will be false.&nbsp; Note that for purposes of this conditional, expressions are always evaluated; if an undefined identifier is used in a %if expression it is replaced with '0' and&nbsp; valuation continues.&nbsp; Subsequent blocks of code will either be assembled if the result of the evaluation is non-zero, or ignored if the result of the evaluation is zero.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> For example:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> %define COLOR 3</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> %if COLOR == 3</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> mov eax,4</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> %endif</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> will result in the mov statement being assembled because the result of the argument evaluation is a nonzero value.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> On the other hand:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> %define ZERO 0</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> %if ZERO</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> mov eax,4</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> %endif</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> results in nothing being assembled because the value of 'ZERO' is zero.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> See the section on </FONT><A HREF="#hs330"><FONT FACE="Arial" SIZE="2">Conditional Processing</FONT></A><FONT FACE="Arial" SIZE="2"> for more on %if-style conditionals.</FONT><BR>
<BR>
<BR>
<FONT FACE="Arial" SIZE="2">%elif</FONT><BR>
<FONT FACE="Arial" SIZE="2"> %elif is a %elif-style conditional that takes a numeric expression as an argument. If the numeric expression evaluates to a non-zero value, the next block will be assembled, otherwise it will be ignored. As with %if, undefined symbols will be replaced with '0' for purposes of the evaulation.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> For example:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> %define COLOR 3</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> %if COLOR == 2</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> mov eax,4</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> %elif COLOR == 3</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> inc eax</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> %endif</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> will result in the mov statement being ignored and the inc statement being assembled because the result of the %if argument evaluation is zero, and the result of the %elif argument evaluation is nonzero.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> See the section on </FONT><A HREF="#hs330"><FONT FACE="Arial" SIZE="2">Conditional Processing</FONT></A><FONT FACE="Arial" SIZE="2"> for more on %elif-style conditionals.</FONT><BR>
<BR>
<BR>
<BR>
<FONT FACE="Arial" SIZE="2"><B>%ifdef</B></FONT><BR>
<FONT FACE="Arial" SIZE="2"> %ifdef is a %if-style conditional that takes an identifer as an argument. If the identifier has been defined with a previous %define or %assign statement, the next block will be&nbsp; assembled, otherwise it will be ignored.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> For example:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> %define COLOR 3</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> %ifdef COLOR</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> mov eax,4</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> %endif</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> will result in the mov statement being assembled because COLOR has been defined.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> Note that a definition declared with %define or %assign must match the argument exactly, whereas a definition declared with %idefine or %iassign can differ in case and still match. %ifdef will not match identifiers declared with %macro or %imacro.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> See the section on </FONT><A HREF="#hs330"><FONT FACE="Arial" SIZE="2">Conditional Processing</FONT></A><FONT FACE="Arial" SIZE="2"> for more on %if-style conditionals.</FONT><BR>
<BR>
<BR>
<BR>
<FONT FACE="Arial" SIZE="2"><B>%ifndef</B></FONT><BR>
<FONT FACE="Arial" SIZE="2"> %ifndef is a %if-style conditional that takes an identifer as an argument. If the identifier has not been defined with a previous %define or %assign statement, the next block will be assembled, otherwise it will be ignored.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> For example:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> %define COLOR 3</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> %ifndef COLOR</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> mov eax,4</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> %endif</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> will result in the mov statement being ignored because COLOR has been defined. Alternatively:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> %undef COLOR</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> %ifndef COLOR</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> mov eax,4</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> %endif</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> will result in the mov statement being assembled because COLOR is not currently defined.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> Note that a definition declared with %define or %assign can have any difference from the argument and trigger assembly of the block, whereas a definition declared with %idefine or %iassign must differ in some way other than in case. %ifndef will assemble the following block for identifiers declared with %macro or %imacro.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> See the section on </FONT><A HREF="#hs330"><FONT FACE="Arial" SIZE="2">Conditional Processing</FONT></A><FONT FACE="Arial" SIZE="2"> for more on %if-style conditionals.</FONT><BR>
<BR>
<BR>
<FONT FACE="Arial" SIZE="2"><B>%else</B></FONT><BR>
<FONT FACE="Arial" SIZE="2"> %else is used to select a block for assembly, when all previous %if-style conditionals and %elif-style conditionals in the same sequence have had their argumentsevaluate to false. For example:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> %define COLOR = 3</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> %if COLOR ==4</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> mov eax,3</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> %else</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> inc eax</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> %endif</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> will result in the mov being ignored, but the inc being assembled, because the evaluation of the %if argument is false.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> See the section on </FONT><A HREF="#hs330"><FONT FACE="Arial" SIZE="2">Conditional Processing</FONT></A><FONT FACE="Arial" SIZE="2"> for more on %else.</FONT><BR>
<BR>
<BR>
<FONT FACE="Arial" SIZE="2"><B>%endif</B></FONT><BR>
<BR>
<BR>
<FONT FACE="Arial" SIZE="2"> %endif is used to end a conditional sequence. Once a conditional sequence is ended, code assembly proceeds as normal, unless the conditional sequence was itself nested within a block of a higher-level conditional sequence that is not being assembled.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> See the section on </FONT><A HREF="#hs330"><FONT FACE="Arial" SIZE="2">Conditional Processing</FONT></A><FONT FACE="Arial" SIZE="2"> for more on %endif.</FONT><BR>

<BR><BR><BR>
<A NAME="hs320"></A>
<FONT FACE="Arial" COLOR="#0000FF" SIZE="5"><B>Basic Extensions to C Preprocessor</B></FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">The basic extensions to the C Preprocessor generally add functionality that is very similar to the functionality already found in the C Preprocessor, but extends it in some way.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"><B>%assign</B></FONT><BR>
<FONT FACE="Arial" SIZE="2"> %assign is similar to the non-functional form of %define, in that it defines text to be substituted for an identifier. Where %assign differs is that the text to be substituted is evaluated as if it were an expression at the time the %assign is encountered. This is useful for example in %rep loops. For example the following code makes a data structure that consists of the integers from 1 to 100, in ascending order:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> %assign WORKING 1</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> %rep 100</FONT><BR>
<FONT FACE="Courier New" SIZE="2">&nbsp;&nbsp; db WORKING</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> %assign WORKING WORKING + 1</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> %endrep</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> But there is another difference with %assign. It is the only preprocessor directive that interacts with data structures in the assembler; so for example the %assign expression can contain expressions involving labels and the program counter. Thus:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> helloWorld db "hello world"</FONT><BR>
<FONT FACE="Courier New" SIZE="2">&nbsp; %assign COUNTER 64 - ($-helloWorld)&nbsp;</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> %assign PADDING ($-helloWorld)</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> %rep COUNTER</FONT><BR>
<FONT FACE="Courier New" SIZE="2">&nbsp;&nbsp; db PADDING</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> %assign PADDING PADDING + 1</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> %endrep</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> puts the string "hello world" in the text, followed by the byte for 11, the byte for 12, etc... up to the byte for 63.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> Note that this latter behavior of interacting with the assembler is only valid if code is being assembled. If the preprocess-only switch is specified on the command line, assembler symbols will not be available, and the latter example will result in errors.</FONT><BR>
<BR>
<BR>
<BR>
<FONT FACE="Arial" SIZE="2"><B>%iassign</B></FONT><BR>
<FONT FACE="Arial" SIZE="2"> %iassign is a form of %assign where the identifier is considered to be case insensitive. So for example:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> %iassign</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> COUNTER 63</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> %rep Counter</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> ...</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> %endrep</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> and similar case variants on the word counter would still result in a loop that executes 63 times.</FONT><BR>
<BR>
<BR>
<FONT FACE="Arial" SIZE="2"><B>%idefine</B></FONT><BR>
<FONT FACE="Arial" SIZE="2"> %idefine is a form of %define where the identifier is assumed to be case insensitive. So for example:&nbsp;</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> %idefine COUNTER 4</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> %idefine counter 4</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> %idefine Counter 4</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> are equivalent statements, and any case variant of the word COUNTER will match for substitution. Note that this case sensitivity only extends to the identifier; any parameters specified in a function-style %idefine are still case-sensitive for purposes of substitution.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"><B>%elifdef</B></FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> %elifdef is a %elif-style conditional that takes an identifer as an argument. If the identifier has been defined with a previous %define or %assign statement, the next block will be assembled, otherwise the next block will be ignored.&nbsp; For example:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> %define COLOR 3</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> %if COLOR == 2</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> mov eax,4</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> %elifdef COLOR</FONT><BR>
<FONT FACE="Courier New" SIZE="2">&nbsp; inc eax</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> %endif</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> will result in the mov statement being ignored and the inc statement being assembled because COLOR has been defined but is not 2.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> Note that a definition declared with %define or %assign must match the argument exactly, whereas a definition declared with %idefine or %iassign can differ in case and still match.&nbsp;&nbsp; %elifdef will not match identifiers declared with %macro or %imacro.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> See the section on </FONT><A HREF="#hs330"><FONT FACE="Arial" SIZE="2">Conditional Processing</FONT></A><FONT FACE="Arial" SIZE="2"> for more on %elif-style conditionals.</FONT><BR>
<BR>
<BR>
<FONT FACE="Arial" SIZE="2"><B>%elifndef</B></FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> %elifndef is a %elif-style conditional that takes an identifer as an argument. If the identifier has not been defined with a previous %define or %assign statement, the next block will be assembled, otherwise the next block will be ignored.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> For example:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> %define COLOR 3</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> %if COLOR == 2</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> mov eax,4</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> %elifndef COLOR</FONT><BR>
<FONT FACE="Courier New" SIZE="2">&nbsp; inc eax</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> %endif</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> will result in nothing being assembled because COLOR is defined but not</FONT><BR>
<FONT FACE="Arial" SIZE="2"> equal to 2.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> Note that a definition declared with %define or %assign can have any difference from the argument and trigger assembly of the block, whereas a definition declared with %idefine or %iassign must differ in some way other than in case.&nbsp; %elifndef will assemble the following block for identifiers declared with %macro or %imacro.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> See the section on </FONT><A HREF="#hs330"><FONT FACE="Arial" SIZE="2">Conditional Processing</FONT></A><FONT FACE="Arial" SIZE="2"> for more on %elif-style conditionals.
</FONT>
<BR><BR><BR>
<A NAME="hs330"></A>
<FONT FACE="Arial" COLOR="#0000FF" SIZE="5"><B>Conditional Processing</B></FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Conditional processing is a way to tell the assembler that some lines of code should be assembled into the program, and other lines may be ignored. There are a variety of conditional processing directives, which use conditions ranging from evaluation of an expression, to string comparison, to type or state of a previous symbol definition. It is useful particularly in configurationmanagement, to allow different configurations of the program to be built for example by changing the command line. It is also useful in conjunction with </FONT><A HREF="#hs370"><FONT FACE="Arial" SIZE="2">multiline macros</FONT></A><FONT FACE="Arial" SIZE="2">, where it can be used to evaluate some characteristic of an argument to a macro.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">The conditional processing statements can be broken into four basic types:</FONT><BR>

<LI><FONT FACE="Arial" SIZE="2">%if-style conditional</FONT>
<LI><FONT FACE="Arial" SIZE="2">%elif-style conditional</FONT>
<LI><FONT FACE="Arial" SIZE="2">%else</FONT>
<LI><FONT FACE="Arial" SIZE="2">%endif</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Conditional processing always starts with a %if-style conditional, and ends with a %endif conditional. Between them them, there can be any number of %elif-style conditionals (including none at all), followed by zero or one %else conditional. A sequence of these conditionals breaks the enclosed code up into multiple blocks.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Conditionals may be nested; in other words each block can be further broken up into smaller blocks with more conditionals that are placed inside the initial conditional. Two conditional</FONT><BR>
<FONT FACE="Arial" SIZE="2">statements are considered to be at the same level if all sets of conditionals within the blocks specified by the conditionals have both a %if-style conditional and a %endif conditional.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Processing starts with the %if-style conditional. Its arguments are evaluated according to the rules for that conditional. If the evaluation returns a value of true, the following block of code is</FONT><BR>
<FONT FACE="Arial" SIZE="2">assembled, and any other blocks up to the %endif conditional which matches this %if-style conditional are ignored</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">If however the evaluation of the %if-style conditional returns false, the following block of code is ignored. Then processing begins with any %elif-style conditionals at the same level, in the order they appear in the code. Each %elif-style conditional is successively evaluated, until the evaluation of one of the arguments returns 'true'. For each %elif-style conditional that evaluates to false, the corresponding block is skipped; if one returns true its code block is assembled and all remaining blocks of code up to the %endif conditional are ignored.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">If the evaluation of the %if-style conditional returns false, and a corresponding %elif-style conditional that returns true cannot be found at the same level (e.g. they all return false or there aren't any), the %else conditional block is assembled if it exists.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">If all the evaluations return false, and there is no %else conditional, none of the blocks are assembled.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Various examples follow, for the %if-style conditional that evaluates expressions:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">%if COLOR == 4</FONT><BR>
<FONT FACE="Courier New" SIZE="2">&nbsp; mov eax,4</FONT><BR>
<FONT FACE="Courier New" SIZE="2">%endif</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">%if COLOR == 4</FONT><BR>
<FONT FACE="Courier New" SIZE="2">&nbsp; mov eax,4</FONT><BR>
<FONT FACE="Courier New" SIZE="2">%else</FONT><BR>
<FONT FACE="Courier New" SIZE="2">&nbsp; mov eax,1</FONT><BR>
<FONT FACE="Courier New" SIZE="2">%endif</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">%if COLOR == 4</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> mov eax,4</FONT><BR>
<FONT FACE="Courier New" SIZE="2">%elif COLOR == 3</FONT><BR>
<FONT FACE="Courier New" SIZE="2">&nbsp; mov eax,3</FONT><BR>
<FONT FACE="Courier New" SIZE="2">%elif COLOR == 2</FONT><BR>
<FONT FACE="Courier New" SIZE="2">mov eax,2</FONT><BR>
<FONT FACE="Courier New" SIZE="2">%endif</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">%if COLOR == 4</FONT><BR>
<FONT FACE="Courier New" SIZE="2">&nbsp; mov eax,4</FONT><BR>
<FONT FACE="Courier New" SIZE="2">%elif COLOR== 3</FONT><BR>
<FONT FACE="Courier New" SIZE="2">&nbsp; mov eax,3</FONT><BR>
<FONT FACE="Courier New" SIZE="2">%elif COLOR == 2</FONT><BR>
<FONT FACE="Courier New" SIZE="2">mov eax,2</FONT><BR>
<FONT FACE="Courier New" SIZE="2">%else</FONT><BR>
<FONT FACE="Courier New" SIZE="2">&nbsp; mov eax,1</FONT><BR>
<FONT FACE="Courier New" SIZE="2">%endif</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Note that when a conditional block is not being assembled, no preprocessor directives within that block will be evaluated either (other than to allow OAsm's preprocessor to keep track of things like nested conditionals)
</FONT>
<BR><BR><BR>
<A NAME="hs340"></A>
<FONT FACE="Arial" COLOR="#0000FF" SIZE="5"><B>Text Comparison Conditionals</B></FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">The Text Comparison Conditionals are used in&nbsp; </FONT><A HREF="#hs330"><FONT FACE="Arial" SIZE="2">Conditional Processing</FONT></A><FONT FACE="Arial" SIZE="2">, to compare two peices of textual data. Each takes as an argument a list of two character sequences, separated by a comma. Each sequence is stripped of leading and trailing spaces, and then the sequences are compared. It does not matter if the sequences are enclosed in quotes.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Depending on the result of the comparison, successive code will be assembled or ignored based on the specific directive specified.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Text Comparison Conditionals are useful for example in conjunction with %macro and %imacro, to evaluate macro arguments.</FONT><BR>
<BR>
<BR>
<FONT FACE="Arial" SIZE="2"><B>%ifidn</B></FONT><BR>
<FONT FACE="Arial" SIZE="2"> %ifidn is a %if-style conditional that compares the two peices of textual data in a case-sensitive manner, and the accompanying code block is assembled if the two peices of data match. For example:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> %define HELLO goodbye</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> %ifidn HELLO, goodbye</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> mov eax,3</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> %endif</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> would result in the mov statement being assembled because thesubstitution for HELLO matches the text goodbye.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> See the section on </FONT><A HREF="#hs330"><FONT FACE="Arial" SIZE="2">Conditional Processing</FONT></A><FONT FACE="Arial" SIZE="2"> for more on %if-style conditionals.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"><B>%ifnidn</B></FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> %ifnidn is a %if-style conditional that compares the two peices of textual data in a case-sensitive manner, and the accompanying code block is assembled if the two peices of data do not match. For example:</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> would result in nothing being assembled because the substitution for HELLO matches the text goodbye. Alternatively:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> %define HELLO goodbye</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> %ifnidn HELLO, hello</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> mov eax,3</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> %endif</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> would result in the the mov instruction being assembled.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> See the section on </FONT><A HREF="#hs330"><FONT FACE="Arial" SIZE="2">Conditional Processing</FONT></A><FONT FACE="Arial" SIZE="2"> for more on %if-style conditionals.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"><B>%elifidn</B></FONT><BR>
<FONT FACE="Arial" SIZE="2"> %elifidn is a %elif-style conditional that compares the two peices of textual data in a case-sensitive manner, and the accompanying code block is assembled if the two peices of ata match. For example:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> %define HELLO goodbye</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> %if HELLO == 1</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> %elifidn HELLO , goodbye</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> mov eax,3</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> %endif</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> would result in the mov statement being assembled because the substitution for HELLO matches the text goodbye.&nbsp; ('goodbye' is not defined so when it is evaluated as a number the result is zero).</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> See the section on </FONT><A HREF="#hs330"><FONT FACE="Arial" SIZE="2">Conditional Processing</FONT></A><FONT FACE="Arial" SIZE="2"> for more on %elif-style conditionals.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"><B>%elifnidn</B></FONT><BR>
<FONT FACE="Arial" SIZE="2"> %elifnidn is a %elif-style conditional that compares the two peices of textual data in a case-sensitive manner, and the accompanying code block is assembled if the two peices of data do not match. For example:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> %define HELLO goodbye</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> %if HELLO = 1</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> %elifnidn goodbye , HELLO</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> mov eax,3</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> %endif</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> would result in nothing being assembled because the substitution for HELLO matches the text goodbye.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> See the section on </FONT><A HREF="#hs330"><FONT FACE="Arial" SIZE="2">Conditional Processing</FONT></A><FONT FACE="Arial" SIZE="2"> for more on %elif-style conditionals.</FONT><BR>
<BR>
<BR>
<BR>
<BR>
<FONT FACE="Arial" SIZE="2"><B>%ifidni</B></FONT><BR>
<FONT FACE="Arial" SIZE="2"> %ifidni is a %if-style conditional that compares the two peices of textual data in a case-insensitive manner, and the accompanying code block is assembled if the two peices of data match. For example:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> %define HELLO goodbye</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> %ifidni HELLO, GOODBYE</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> mov eax,3</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> %endif</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> would result in the mov statement being assembled because thesubstitution for HELLO matches the text goodbye.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> See the section on </FONT><A HREF="#hs330"><FONT FACE="Arial" SIZE="2">Conditional Processing</FONT></A><FONT FACE="Arial" SIZE="2"> for more on %if-style conditionals.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"><B>%ifnidni</B></FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> %ifnidni is a %if-style conditional that compares the two peices of textual data in a case-insensitive manner, and the accompanying code block is assembled if the two peices of data do not match. For example:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> %define HELLO goodbye</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> %ifnidni HELLO , GOODBYE</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> mov eax,3</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> %endif</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> would result in nothing being assembled because the substitution for HELLO matches the text goodbye. Alternatively:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> %define HELLO goodbye</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> %ifnidni HELLO, hello</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> mov eax,3</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> %endif</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> would result in the the mov instruction being assembled.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> See the section on </FONT><A HREF="#hs330"><FONT FACE="Arial" SIZE="2">Conditional Processing</FONT></A><FONT FACE="Arial" SIZE="2"> for more on %if-style conditionals.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"><B>%elifidni</B></FONT><BR>
<FONT FACE="Arial" SIZE="2"> %elifidni is a %elif-style conditional that compares the two peices of textual data in a case-insensitive manner, and the accompanying code block is assembled if the two peices of ata match. For example:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> %define HELLO goodbye</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> %if HELLO == 1</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> %elifidni HELLO , GOODBYE</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> mov eax,3</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> %endif</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> would result in the mov statement being assembled because the substitution for HELLO matches the text goodbye.&nbsp; ('goodbye' is not defined so when it is evaluated as a number the result is zero).</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> See the section on </FONT><A HREF="#hs330"><FONT FACE="Arial" SIZE="2">Conditional Processing</FONT></A><FONT FACE="Arial" SIZE="2"> for more on %elif-style conditionals.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"><B>%elifnidni</B></FONT><BR>
<FONT FACE="Arial" SIZE="2"> %elifnidni is a %elif-style conditional that compares the two peices of textual data in a case-insensitive manner, and the accompanying code block is assembled if the two peices of data do not match. For example:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> %define HELLO goodbye</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> %if HELLO = 1</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> %elifnidni GOODBYE , HELLO</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> mov eax,3</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> %endif</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> would result in nothing being assembled because the substitution for HELLO matches the text goodbye.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> See the section on </FONT><A HREF="#hs330"><FONT FACE="Arial" SIZE="2">Conditional Processing</FONT></A><FONT FACE="Arial" SIZE="2"> for more on %elif-style conditionals.</FONT><BR>
<BR>
<BR>
<BR>
<BR>

<BR><BR><BR>
<A NAME="hs350"></A>
<FONT FACE="Arial" COLOR="#0000FF" SIZE="5"><B>Token Classification Conditionals</B></FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">The Token Type Classification conditionals are used in </FONT><A HREF="#hs330"><FONT FACE="Arial" SIZE="2">Conditional Processing</FONT></A><FONT FACE="Arial" SIZE="2">.&nbsp; They take a character stream, and determine what kind of token the assembler will think it would be if it were to assemble the stream as part of processing an instruction or directive.&nbsp; This is useful for example within multiline macro definitions, to change the behavior of a macro based on the type of data in one or more of the arguments. Token Type classification directives can detect one of three types of token: labels, numbers, and strings.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"><B>%ifid</B></FONT><BR>
<FONT FACE="Arial" SIZE="2"> %ifid is a %if-style conditional that detects if the token could be a label, and processes the following block if it is.</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> %ifid myLabel</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> mov eax,3</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> %endif</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> would result in the mov statement being assembled because myLabel matches a character sequence that could be used in a label. It does not matter if myLabel has actually been defined; the fact that it could be assembled as a label is all that is needed.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> See the section on </FONT><A HREF="#hs330"><FONT FACE="Arial" SIZE="2">Conditional Processing</FONT></A><FONT FACE="Arial" SIZE="2"> for more on %if-style conditionals.</FONT><BR>
<BR>
<BR>
<BR>
<FONT FACE="Arial" SIZE="2"><B>%ifnid</B></FONT><BR>
<FONT FACE="Arial" SIZE="2"> %ifnid is a %if-style conditional that detects if the token could be a label, and processes the following block if it is not.</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> %ifnid 5</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> mov eax,3</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> %endif</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> would result in the mov statement being assembled because 5 is anumber, and does not match the character sequence required for a label.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> See the section on </FONT><A HREF="#hs330"><FONT FACE="Arial" SIZE="2">Conditional Processing</FONT></A><FONT FACE="Arial" SIZE="2"> for more on %if-style conditionals.</FONT><BR>
<BR>
<BR>
<FONT FACE="Arial" SIZE="2"><B>%elifid</B></FONT><BR>
<FONT FACE="Arial" SIZE="2"> %elifid is a %elif-style conditional that detects if the token could be a label, and processes the following block if it is.</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> %if 1 == 2</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> %elifid myLabel</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> mov eax,3</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> %endif</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> would result in the mov statement being assembled because myLabel matches a character sequence that could be used in a label. It does not matter if myLabel has actually been defined; the fact that it could be assembled as a label is all that is needed.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> See the section on </FONT><A HREF="#hs330"><FONT FACE="Arial" SIZE="2">Conditional Processing</FONT></A><FONT FACE="Arial" SIZE="2"> for more on %elif-style conditionals.</FONT><BR>
<BR>
<BR>
<FONT FACE="Arial" SIZE="2"><B>%elifnid</B></FONT><BR>
<FONT FACE="Arial" SIZE="2"> %elifnid is a %elif-style conditional that detects if the token could be a label, and processes the following block if it is not.</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> %if 1 == 2</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> %elifnid 5</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> mov eax,3</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> %endif</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> would result in the mov statement being assembled because 5 is a number, and does not match the character sequence required for a label.&nbsp;</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> See the section on </FONT><A HREF="#hs330"><FONT FACE="Arial" SIZE="2">Conditional Processing</FONT></A><FONT FACE="Arial" SIZE="2"> for more on %elif-style conditionals.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"><B>%ifnum</B></FONT><BR>
<FONT FACE="Arial" SIZE="2"> %ifnum is a %if-style conditional that detects if the token could be a number, and processes the following block if it is.</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> %ifnum 5</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> mov eax,3</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> %endif</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> would result in the mov statement being assembled because 5 matches a character sequence that could be used as a number.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> See the section on </FONT><A HREF="#hs330"><FONT FACE="Arial" SIZE="2">Conditional Processing</FONT></A><FONT FACE="Arial" SIZE="2"> for more on %if-style conditionals.</FONT><BR>
<BR>
<BR>
<FONT FACE="Arial" SIZE="2"><B>%ifnnum</B></FONT><BR>
<FONT FACE="Arial" SIZE="2"> %ifnnum is a %if-style conditional that detects if the token could be a number, and processes the following block if it is not.</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> %ifnnum mylabel</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> mov eax,3</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> %endif</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> would result in the mov statement being assembled because mylabel does not match a characer sequence that could be a number.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> See the section on </FONT><A HREF="#hs330"><FONT FACE="Arial" SIZE="2">Conditional Processing</FONT></A><FONT FACE="Arial" SIZE="2"> for more on %if-style conditionals.</FONT><BR>
<BR>
<BR>
<FONT FACE="Arial" SIZE="2"><B>%elifnum</B></FONT><BR>
<FONT FACE="Arial" SIZE="2"> %elifnum is a %elif-style conditional that detects if the token could be a number, and processes the following block if it is.</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> %if 1 == 2</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> %elifnum 5</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> mov eax,3</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> %endif</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> would result in the mov statement being assembled because 5 matches a character sequence that could be used as a number.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> See the section on </FONT><A HREF="#hs330"><FONT FACE="Arial" SIZE="2">Conditional Processing</FONT></A><FONT FACE="Arial" SIZE="2"> for more on %elif-style conditionals.</FONT><BR>
<BR>
<BR>
<FONT FACE="Arial" SIZE="2"><B>%elifnnum</B></FONT><BR>
<FONT FACE="Arial" SIZE="2"> %elifnnum is a %elif-style conditional that detects if the token could be a number, and processes the following block if it is not.</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> %if 1 == 2</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> %elifnnum myLabel</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> mov eax,3</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> %endif</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> would result in the mov statement being assembled because mylabel does not match a character sequence which could be a number</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> See the section on </FONT><A HREF="#hs330"><FONT FACE="Arial" SIZE="2">Conditional Processing</FONT></A><FONT FACE="Arial" SIZE="2"> for more on %elif-style conditionals.</FONT><BR>
<BR>
<BR>
<FONT FACE="Arial" SIZE="2"><B>%ifstr</B></FONT><BR>
<FONT FACE="Arial" SIZE="2"> %ifstr is a %if-style conditional that detects if the token could be a string, and processes the following block if it is.</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> %ifstr "Hello World"</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> mov eax,3</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> %endif</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> would result in the mov statement being assembled because "Hello World"&nbsp; a character sequence that could be used as a string.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> See the section on </FONT><A HREF="#hs330"><FONT FACE="Arial" SIZE="2">Conditional Processing</FONT></A><FONT FACE="Arial" SIZE="2"> for more on %if-style conditionals.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"><B>%ifnstr</B></FONT><BR>
<FONT FACE="Arial" SIZE="2"> %ifnstr is a %if-style conditional that detects if the token could be a string, and processes the following block if it is not.</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> %ifnstr 5</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> mov eax,3</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> %endif</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> would result in the mov statement being assembled because 5 is anumber, and does not match the character sequence required for a string.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> See the section on </FONT><A HREF="#hs330"><FONT FACE="Arial" SIZE="2">Conditional Processing</FONT></A><FONT FACE="Arial" SIZE="2"> for more on %if-style conditionals.</FONT><BR>
<BR>
<BR>
<FONT FACE="Arial" SIZE="2"><B>%elifstr</B></FONT><BR>
<FONT FACE="Arial" SIZE="2"> %elifstr is a %elif-style conditional that detects if the token could be a string, and processes the following block if it is.</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> %if 1 == 2</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> %elifstr "hello world"</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> mov eax,3</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> %endif</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> would result in the mov statement being assembled because "hello world" matches a character sequence that could be used as a string.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> See the section on </FONT><A HREF="#hs330"><FONT FACE="Arial" SIZE="2">Conditional Processing</FONT></A><FONT FACE="Arial" SIZE="2"> for more on %elif-style conditionals.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"><B>%elifnstr</B></FONT><BR>
<FONT FACE="Arial" SIZE="2"> %elifnstr is a %elif-style conditional that detects if the token could be a string, and processes the following block if it is not.</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> %if 1 == 2</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> %elifnstr 5</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> mov eax,3</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> %endif</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> would result in the mov statement being assembled because 5 is a number, and does not match the character sequence required for a string.&nbsp;</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> See the section on </FONT><A HREF="#hs330"><FONT FACE="Arial" SIZE="2">Conditional Processing</FONT></A><FONT FACE="Arial" SIZE="2"> for more on %elif-style conditionals.</FONT><BR>
<BR>
<BR>
<BR>
<BR>
<BR>
<BR>

<BR><BR><BR>
<A NAME="hs360"></A>
<FONT FACE="Arial" COLOR="#0000FF" SIZE="5"><B>Context-Related Extensions</B></FONT><BR>
<BR>
<BR>
<FONT FACE="Arial" SIZE="2">The Context Related extensions are used to define preprocessor contexts. A preprocessor context can be used to create a memory of state information, between different invocations of multiline macros. For example, a set of macros could be defined to mimic high-level control functions such as loops and if statements.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Many combinations of contexts can exist simultaneously.&nbsp; OAsm maintains a stack of all open contexts, pushing new contexts on the top of the stack and removing old contents from the top of the stack.&nbsp; Each context has a name, and a state which can include context-specific variables and definitions. The name of the context on top of the stack can be examined to determine what the current context is, or changed. It might be useful to change it for example if two macros maintain a context, but a third macro might change the context based on its arguments, e.g. to allow processing by a fourth macro which would not succeed if the name on top of the context stack wasn't correct.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Within a context, context-specific definitions and labels may be defined for reference from other macros. Each context-specific definition is in scope while that context is in scope, e.g. while the context is on top of the context-stack. If a context is open multiple times simultaneously, each instance of the open context is unique, even though the textual representation labels in in the source code for that context may be the same.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Context-specific definitions and labels start with the sequence '%$' and then contain a label start character and other label characters, just like other identifiers. For example:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">%$HelloWorld</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">could be used in a context-specific definition or label, and would signify that that label goes with the current context. As an example consider the two macros</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">%macro BEGIN 0</FONT><BR>
<FONT FACE="Courier New" SIZE="2">%push MyBegin</FONT><BR>
<FONT FACE="Courier New" SIZE="2">%$HelloWorld:</FONT><BR>
<FONT FACE="Courier New" SIZE="2">%endmacro</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">%macro FOREVER 0</FONT><BR>
<FONT FACE="Courier New" SIZE="2">%ifctx MyBegin</FONT><BR>
<FONT FACE="Courier New" SIZE="2">jmp %$HelloWorld</FONT><BR>
<FONT FACE="Courier New" SIZE="2">%pop</FONT><BR>
<FONT FACE="Courier New" SIZE="2">%else</FONT><BR>
<FONT FACE="Courier New" SIZE="2">%error FOREVER loop without matching BEGIN</FONT><BR>
<FONT FACE="Courier New" SIZE="2">%endif</FONT><BR>
<FONT FACE="Courier New" SIZE="2">%endmacro</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">could be used to implement an infinite loop as follows, if the macros are used in a pair.&nbsp;</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">BEGIN</FONT><BR>
<FONT FACE="Courier New" SIZE="2">inc EAX</FONT><BR>
<FONT FACE="Courier New" SIZE="2">FOREVER</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Contexts can also have 'local' macro definitions:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">%push MY_CONTEXT</FONT><BR>
<FONT FACE="Courier New" SIZE="2">%define %$four 4</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">results in a definition that will only be valid while this instance of MY_CONTEXT is on top of the context stack.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">When contexts are used, they don't have to appear within a multiline macro definition, but it is often useful to use them this way.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Note: OAsm does not separate context-specific label names into different namespaces. Instead, a prefix is inserted before the symbol's name and the symbol is entered in the global symbol table. The prefix takes the form of a non-local label, with context-instance identifying information. This identifying information is simply an integer followed by the character '$'. For example if the context instance number is 54, the label %$Hello would be translated to:</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> </FONT><FONT FACE="Courier New" SIZE="2">..@54$Hello</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">by the preprocessor. Non-local labels of this general form should be avoided as they may collide with labels defined locally within a</FONT><BR>
<FONT FACE="Arial" SIZE="2">context. This also applies to locally defined&nbsp; %define statements.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"><B>%push</B></FONT><BR>
<FONT FACE="Arial" SIZE="2"> %push creates a new context and pushes it on the top of the context stack:</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> </FONT><FONT FACE="Courier New" SIZE="2">%push CONTEXT_NAME</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> 'local' definitions can be made within this context as indicated in the introduction.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> If %push is used multiple times with the same context name, each context is unique even though the names are the same. So for example:</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> </FONT><FONT FACE="Courier New" SIZE="2">%push MY_CONTEXT</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> %$contextLabel:</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> %push MY_CONTEXT</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> %$contextLabel:</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> is valid, because the two labels are named locally to the context and are in different context instances. When the label is used, it will be matched to the context currently on top of the context stack.</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"><B>%pop</B></FONT><BR>
<FONT FACE="Arial" SIZE="2"> %pop removes the context at the top of the context stack:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> %push MY_CONTEXT</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> %pop&nbsp;</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> results in MY_CONTEXT no longer being active, and the context that was below it on the context-stack becomes active. Note, you should use any labels or definitions that are specific to a context before it is popped. Once a context is popped off the stack, its state is never recoverable.&nbsp;</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"><B>%repl</B></FONT><BR>
<FONT FACE="Arial" SIZE="2"> %repl changes the name of the context at the top of the context-stack. For example:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> %push MY_CONTEXT</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> creates a context called MY_CONTEXT. If that is followed by:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> %repl NEW_NAME</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> the context will now be called NEW_NAME. When a context is renamed this way, all previous local definitions and labels are still accessible while that context is on top of the context stack. The only affect of renaming the context is that conditionals which act on context names will be matched against the new name instead of the old one.</FONT><BR>
<BR>
<BR>
<FONT FACE="Arial" SIZE="2"><B>%ifctx</B></FONT><BR>
<FONT FACE="Arial" SIZE="2"> %ifctx is a %if-style conditional that&nbsp; takes a context name as an argument. If the context name matches the name of the context on top of the context stack, the next block is assembled, otherwise it is not.&nbsp; For example:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> %push MY_NAME</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> %ifctx MY_NAME</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> mov eax,4</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> %endif</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> will result in the mov statement being assembled because the top of the context stack is named MY_NAME, whereas:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> %push MY_NAME</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> %ifctx ANOTHER_NAME</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> mov eax,4</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> %endif</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> will result in nothing being assembled because the name of the top of the context stack does not match the argument to %ifctx.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> See the section on </FONT><A HREF="#hs330"><FONT FACE="Arial" SIZE="2">Conditional Processing</FONT></A><FONT FACE="Arial" SIZE="2"> for more on %if-style conditionals.</FONT><BR>
<BR>
<BR>
<FONT FACE="Arial" SIZE="2"><B>%ifnctx</B></FONT><BR>
<FONT FACE="Arial" SIZE="2"> %ifnctx is a %if-style conditional that takes a context name as an argument. If the context name does not match the name of the context on top of the context stack, the next block is assembled, otherwise it is not.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> For example:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> %push MY_NAME</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> %ifnctx MY_NAME</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> mov eax,4</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> %endif</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> will result in nothing being assembled because the name of the context on top of the stack matches the argument.</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> %push MY_NAME</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> %ifnctx ANOTHER_NAME</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> mov eax,4</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> %endif</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> will result in the mov being assembled because the names do not match.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> See the section on </FONT><A HREF="#hs330"><FONT FACE="Arial" SIZE="2">Conditional Processing</FONT></A><FONT FACE="Arial" SIZE="2"> for more on %if-style conditionals.</FONT><BR>
<BR>
<BR>
<BR>
<FONT FACE="Arial" SIZE="2"><B>%elfictx</B></FONT><BR>
<FONT FACE="Arial" SIZE="2"> %elifctx is a %elif-style conditional that takes a context name as an argument.&nbsp; If the context name matches the name of the context on top of the context stack, the next block is assembled, otherwise it is not.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> For example:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> %push MY_NAME</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> %if 44</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> %elifctx MY_NAME</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> mov eax,4</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> %endif</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> will result in the mov statement being assembled because the top of the context stack is named MY_NAME.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> See the section on </FONT><A HREF="#hs330"><FONT FACE="Arial" SIZE="2">Conditional Processing</FONT></A><FONT FACE="Arial" SIZE="2"> for more on %elif-style conditionals.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"><B>%elifnctx</B></FONT><BR>
<FONT FACE="Arial" SIZE="2"> %elifnctx is a %elif-style conditional that takes a context name as an argument. If the context name does not match the name of the context on top of the context stack, the next block is assembled, otherwise it is not.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> For example:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> %push MY_NAME</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> %if 44</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> %elifctx MY_NAME</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> mov eax,4</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> %endif</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> will result in nothing being assembled because the names match.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> See the section on </FONT><A HREF="#hs330"><FONT FACE="Arial" SIZE="2">Conditional Processing</FONT></A><FONT FACE="Arial" SIZE="2"> for more on %elif-style conditionals.
</FONT>
<BR><BR><BR>
<A NAME="hs370"></A>
<FONT FACE="Arial" COLOR="#0000FF" SIZE="5"><B>Multi-Line Macro Extensions</B></FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Multiline macro extensions allow definition of types of macros that are more familiar to assembly language programmers. Such macros may contain an arbitrary number of assembly language statements and preprocessor directives. These macros have three parts: the macro header, the macro body, and the macro invocation.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">The macro header and macro body are used when defining the macro.&nbsp; For example a simple multiline macro that gives a new name to NOP might look as follows:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">%macro MY_NOP 0</FONT><BR>
<FONT FACE="Courier New" SIZE="2">nop</FONT><BR>
<FONT FACE="Courier New" SIZE="2">%endmacro</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">here MY_NOP is the name of the macro, which is case-sensitive since %macro was used rather than %imacro. The zero in the header following MY_NOP indicates this macro has no parameters. The body of the macro is the 'nop' statement, and the macro definition ends with %endmacro.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">After the macro is defined, it can be invoked as many times as necessary. For example:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">MY_NOP</FONT><BR>
<FONT FACE="Courier New" SIZE="2">MY_NOP</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">causes the assembler to assemble two 'nop' statements based on the above definition.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">A macro can have parameters:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">%macro MY_MOV 2</FONT><BR>
<FONT FACE="Courier New" SIZE="2">mov %1, %2</FONT><BR>
<FONT FACE="Courier New" SIZE="2">%endmacro</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">In this macro, the 2 in the header signifies the macro takes exactly two arguments. Specifying more arguments, or less, during and invocation, will result in an error. The %1 and %2 are</FONT><BR>
<FONT FACE="Arial" SIZE="2">substituted with the first and second arguments. For example:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">MY_MOV eax,ebx</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">becomes:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">mov eax,ebx</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Macros can have a variable number of parameters. In:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">%macro MY_PUSH 1-4</FONT><BR>
<FONT FACE="Courier New" SIZE="2">%rep %0</FONT><BR>
<FONT FACE="Courier New" SIZE="2">push %1</FONT><BR>
<FONT FACE="Courier New" SIZE="2">%rotate 1</FONT><BR>
<FONT FACE="Courier New" SIZE="2">%endrep</FONT><BR>
<FONT FACE="Courier New" SIZE="2">%endmacro</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">the header specifies the macro can have between one and four arguments. In the body, the %0 gives the number of arguments that were actually specified. The %rotate rotates the arguments left by one, so that the contents of %2 moves to %1, the contents of %3&nbsp; moves to %2, and so forth. The contents of %1 moves to the end of the list.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Invoking this macro as follows:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">MY_PUSH eax,ebx,ecx</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">results in the preprocessor generating the following instructions:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">push eax</FONT><BR>
<FONT FACE="Courier New" SIZE="2">push ebx</FONT><BR>
<FONT FACE="Courier New" SIZE="2">push ecx</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">This can be made just a little bit better through the use of the infinite argument list specifier:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">%macro MY_PUSH 1-*</FONT><BR>
<FONT FACE="Courier New" SIZE="2">%rep %0</FONT><BR>
<FONT FACE="Courier New" SIZE="2">push %1</FONT><BR>
<FONT FACE="Courier New" SIZE="2">%rotate 1</FONT><BR>
<FONT FACE="Courier New" SIZE="2">%endrep</FONT><BR>
<FONT FACE="Courier New" SIZE="2">%endmacro</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">where the * in the header means there is no practical limit to the number of arguments (there is a limit, but it wouldn't be realistic to type that many arguments even with a code-generating program). Now the macro isn't limited to four push statements; it can push as many things as are listed in the macro invocation.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">A corresponding MY_POP can be created with minor changes:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">%macro MY_POP 1-*</FONT><BR>
<FONT FACE="Courier New" SIZE="2">%rep %0</FONT><BR>
<FONT FACE="Courier New" SIZE="2">%rotate -1</FONT><BR>
<FONT FACE="Courier New" SIZE="2">pop %1</FONT><BR>
<FONT FACE="Courier New" SIZE="2">%endrep</FONT><BR>
<FONT FACE="Courier New" SIZE="2">%endmacro</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">where the rotate statement now shifts right instead of left, with the rightmost argument appearing in %1.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Occasionaly it is beneficial to specify that you need some arguments, then you want the rest of the command line:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">%define STRINGIZE(s) #s</FONT><BR>
<FONT FACE="Courier New" SIZE="2">%macro MY_MSG 1+&nbsp;</FONT><BR>
<FONT FACE="Courier New" SIZE="2">db&nbsp; %1,STRINGIZE(%2)</FONT><BR>
<FONT FACE="Courier New" SIZE="2">%endmacro</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Where the + symbol means anything beyond the first argument should be gathered together and make another argument. This does include comma characters; after the first argument's separating comma commas will no longer be processed with this syntax. As an example invocation:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">MY_MSG 44, hello there, world</FONT><BR>
<FONT FACE="Courier New" SIZE="2">would translate to:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">db 44,"hello there, world"</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Of course the + symbol may be combined with specifying variable length argument lists as shown in the following header:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">%macro do_something 1-4+</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Another use for the + symbol is to get the entire argument list of a macro invocation, unparsed, as shown in the following header:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">%macro do_something 0+</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Sometimes it is useful to include the comma character in the argument for a macro invocation:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">%macro define_numbers 3</FONT><BR>
<FONT FACE="Courier New" SIZE="2">db %1,%2,%3</FONT><BR>
<FONT FACE="Courier New" SIZE="2">%endmacro</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">define_numbers {1,2},3,4</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">to result in:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">db 1,2,3,4</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">When variable length argument lists are used, everything starting with the first variable argument can have a default value. For example with the macro header:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">%macro define_strings 1-3 "hello", "there"</FONT><BR>
<FONT FACE="Courier New" SIZE="2">%rep %0</FONT><BR>
<FONT FACE="Courier New" SIZE="2">db %1</FONT><BR>
<FONT FACE="Courier New" SIZE="2">%rotate 1</FONT><BR>
<FONT FACE="Courier New" SIZE="2">%endrep</FONT><BR>
<FONT FACE="Courier New" SIZE="2">%endmacro</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">defaults the second and third arguments to "hello" and "there" respectively, if they are not specified in the invocation. For example:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">define_strings "one"</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">results in:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">db "one"</FONT><BR>
<FONT FACE="Courier New" SIZE="2">db "hello"</FONT><BR>
<FONT FACE="Courier New" SIZE="2">db "there"</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">whereas:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">define_strings "one", "two"</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">results in:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">db "one"</FONT><BR>
<FONT FACE="Courier New" SIZE="2">db "two"</FONT><BR>
<FONT FACE="Courier New" SIZE="2">db "there"</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Many of the above macros are unexciting, and perform functions that could be done other ways e.g. with %define. A more interesting example of a multiline macro is as follows:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">%macro power 2</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">mov ecx,%1</FONT><BR>
<FONT FACE="Courier New" SIZE="2">mov eax,1</FONT><BR>
<FONT FACE="Courier New" SIZE="2">jecxz %noop</FONT><BR>
<FONT FACE="Courier New" SIZE="2">mov eax,%2</FONT><BR>
<FONT FACE="Courier New" SIZE="2">cmp ecx,1</FONT><BR>
<FONT FACE="Courier New" SIZE="2">jz %noop</FONT><BR>
<FONT FACE="Courier New" SIZE="2">%local:</FONT><BR>
<FONT FACE="Courier New" SIZE="2">imul eax,%2</FONT><BR>
<FONT FACE="Courier New" SIZE="2">loop %local</FONT><BR>
<FONT FACE="Courier New" SIZE="2">%noop:</FONT><BR>
<FONT FACE="Courier New" SIZE="2">%endmacro</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">which creates code to raise the second argument to the power of the first argument, and leaves the result in eax. An example invocation:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">power 2,3</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">which generates code to return 3 squared in eax. Here we have introduced local labels in macros, which are similar in form to local labels in contexts, except that the macro version does not have a dollars symbol. Such local labels are in scope for a single invocation of the macro; each time the macro is invoked the label will have a different context.&nbsp;</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">As with context-specific labels, the assembler does not implement multiple symbol tables but instead uses a non-local label name.The non-local label name consists of ..@ followed by a context id followed by a period followed by the label name. For example, the labels in the above example would be translated to:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">..@54.local</FONT><BR>
<FONT FACE="Courier New" SIZE="2">..@54.noop</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">if the context identifier for the current macro invocation is 54. non-local labels fitting this general format should not appear in the source code, as there is a chance they will conflict with label names chosen by the preprocessor.</FONT><BR>
<BR>
<BR>
<FONT FACE="Arial" SIZE="2"><B>%macro</B></FONT><BR>
<FONT FACE="Arial" SIZE="2"> %macro starts a macro definition. The name of the macro is case-sensitive.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"><B>%imacro</B></FONT><BR>
<FONT FACE="Arial" SIZE="2"> %imacro starts a macro definition. The name of the macro is not case-sensitive.</FONT><BR>
<BR>
<BR>
<FONT FACE="Arial" SIZE="2"><B>%endmacro</B></FONT><BR>
<FONT FACE="Arial" SIZE="2"> %endmacro ends a macrodefinition.</FONT><BR>
<BR>
<BR>
<FONT FACE="Arial" SIZE="2"><B>%rotate</B></FONT><BR>
<FONT FACE="Arial" SIZE="2"> %rotate rotates the macro argument list for the current invocation a number of times specified in the argument. If the number of times is positive, the arguments are rotated left, with the leftmost arguments going to the end of the list. If the number of times is negative, the arguments are rotated right, with the rightmost arguments going to the beginning of the list.</FONT><BR>

<BR><BR><BR>
<A NAME="hs380"></A>
<FONT FACE="Arial" COLOR="#0000FF" SIZE="5"><B>Repeat Block Extensions</B></FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">The Repeat Block Extensions allow a method for replicating lines of code. In the simplest case, a sequence of instructions or data can be literally repeated a fixed number of times:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">%rep 10</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> nop</FONT><BR>
<FONT FACE="Courier New" SIZE="2">%endrep</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">causes the preprocessor to present 10 nop instructions to the assembler. In a more complex case, %assign can be used to define a function that varies with each loop iteration, allowing easy development of lookup tables:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">%assign i 20</FONT><BR>
<FONT FACE="Courier New" SIZE="2">%rep 10</FONT><BR>
<FONT FACE="Courier New" SIZE="2">db i</FONT><BR>
<FONT FACE="Courier New" SIZE="2">%assign i i - 1</FONT><BR>
<FONT FACE="Courier New" SIZE="2">%endrep</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">puts the numbers from 20 to 11 in a table, in decreasing order.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">This type of functionality could be used with more complex functions, for example %rep would be one way a CRC lookup table could be developed with OAsm.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">In another case the loop count could be made to vary based on previous declarations:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">hello db "Hello World"</FONT><BR>
<FONT FACE="Courier New" SIZE="2">%assign count 64 - ($-Hello)</FONT><BR>
<FONT FACE="Courier New" SIZE="2">%rep count</FONT><BR>
<FONT FACE="Courier New" SIZE="2">db 0</FONT><BR>
<FONT FACE="Courier New" SIZE="2">%endrep</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">While the latter example is not too exciting and could be done other ways, e.g. with the resb or times directives, more complex functions could be integrated into this type of loop to generate different kinds of data.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Repeat blocks may be nested. For example:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">%assign i 10</FONT><BR>
<FONT FACE="Courier New" SIZE="2">%rep 3</FONT><BR>
<FONT FACE="Courier New" SIZE="2">%rep 3</FONT><BR>
<FONT FACE="Courier New" SIZE="2">db i</FONT><BR>
<FONT FACE="Courier New" SIZE="2">%assign i i + 1</FONT><BR>
<FONT FACE="Courier New" SIZE="2">%endrep</FONT><BR>
<FONT FACE="Courier New" SIZE="2">%assign i i - 6</FONT><BR>
<FONT FACE="Courier New" SIZE="2">%endrep</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">generates enough db statements to define the following sequence:</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">10, 11, 12, 7, 8, 9, 4, 5, 6</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Repeat blocks can be exited prematurely. If a %exitrep directive is parsed while a repeat block is being processed, the innermost repeat block exits immediately. Generally, one would use preprocessor conditionals to prevent the %exitrep directive from being processed, until some condition occurs. For example to pop all contexts named "MY_CONTEXT" from the top of the context stack:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">%repeat 1000</FONT><BR>
<FONT FACE="Courier New" SIZE="2">&nbsp;&nbsp;&nbsp;&nbsp;</FONT><BR>
<FONT FACE="Courier New" COLOR="#00FF00" SIZE="2"> // 1000 is an arbitrary value</FONT><BR>
<FONT FACE="Courier New" SIZE="2">%ifnctx MY_CONTEXT</FONT><BR>
<FONT FACE="Courier New" SIZE="2">%exitrep</FONT><BR>
<FONT FACE="Courier New" SIZE="2">%endif</FONT><BR>
<FONT FACE="Courier New" SIZE="2">%pop</FONT><BR>
<FONT FACE="Courier New" SIZE="2">%endrep</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"><B>%rep</B></FONT><BR>
<FONT FACE="Arial" SIZE="2"> %rep is used to start a repeat block. It takes one argument: the number of repetitions to go through.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"><B>%endrep</B></FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> %endrep is used to end a repeat block. It takes no arguments</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"><B>%exitrep</B></FONT><BR>
<FONT FACE="Arial" SIZE="2"> %exitrep is used to exit a repeat block prematurely.
</FONT>
<BR><BR><BR>
<A NAME="hs390"></A>
<FONT FACE="Arial" COLOR="#0000FF" SIZE="5"><B>OGrep</B></FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">OGrep is a utility that searches for text within files. It is capable of matching text with a direct string comparison, with or without case sensitivity. It also is capable of matching text within a file against </FONT><A HREF="#hs410"><FONT FACE="Arial" SIZE="2">regular expressions</FONT></A><FONT FACE="Arial" SIZE="2">. Regular expressions allow a mechanism for specifying ways to match text, while specifying parts of the text which can vary and still match. For example the '.' character matches any other character, so a regular expression such as 'a.c' would match any three-character string starting with 'a' and ending with 'c'. More powerful matching is also possible, such as matching sequences of the same character, matching against any character in a specified set, and so forth.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">The general format of an OGrep </FONT><A HREF="#hs400"><FONT FACE="Arial" SIZE="2">command line</FONT></A><FONT FACE="Arial" SIZE="2"> is as follows:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">OGrep [options] match-string list-of-files</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">OGrep will search in the list-of-files for text that matches the match-string, and list file and optionally line number information for each match</FONT><BR>
<FONT FACE="Arial" SIZE="2">found. In simple cases the match string will not be surrounded by quotes, but in more complex cases involving spacing characters and special</FONT><BR>
<FONT FACE="Arial" SIZE="2">symbols it may be necessary to quote the match-string.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">OGrep has a powerful regular expression matcher, which is turned on by default.However there is a command line option to disable it. When it is turned on some characters will not be matched directly against the text, but will be interpreted in a way that allows the program to perform abstract types of matches.&nbsp;</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">There are several types of matching groups:</FONT><BR>

<LI><FONT FACE="Arial" SIZE="2">Match a character or sequence of the same character</FONT>
<LI><FONT FACE="Arial" SIZE="2">Match the start or end of a line</FONT>
<LI><FONT FACE="Arial" SIZE="2">Match the start, end, or middle of a word</FONT>
<LI><FONT FACE="Arial" SIZE="2">Match one character out of a set of characters</FONT>
<LI><FONT FACE="Arial" SIZE="2">A match can be specified to be repeated at another point within the sequence</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Some of these matching algorithms can be combined, for example matching one character out of a set of characters can be combined with matching a sequence of characters to find words consisting of characters in a subset of the letters and numbers.
</FONT>
<BR><BR><BR>
<A NAME="hs400"></A>
<FONT FACE="Arial" COLOR="#0000FF" SIZE="5"><B>Command Line</B></FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">The general format of an OGrep command line is as follows:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">OGrep [options] match-string list-of-files</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Where [options] are command line options, and the match-string is searched for within the list-of-files.&nbsp; Matches are listed with file and optionally line number. The files in the list-of-files may contain wildcards, for example:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">OGrep "while" *.c</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Looks through all C language source files in the current directory for the word while.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">By default the match-string is assumed to hold a </FONT><A HREF="#hs410"><FONT FACE="Arial" SIZE="2">regular expression</FONT></A><FONT FACE="Arial" SIZE="2">.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Following is a list of the command line switches that OGrep supports.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"><B>-?</B> Getting help</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> OGrep usually has rather abbreviated usage text.&nbsp; To get more detail, use this switch.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"><B>-i</B> case sensitivity</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> By default OGrep performs case-sensitive matching.&nbsp; This switch will change it to use case-insensitive matching.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"><B>-r</B> disable regular expressions</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> By default OGrep uses regular expression pattern matching.&nbsp; To use exact matches instead, specify this option</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"><B>-d</B> recurse through subdirectories</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> In some instances it is necessary to have OGrep parse all the files in an entire directory tree.&nbsp; This switch is used to allow for that behavior.&nbsp; For example:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> OGrep -d "while" *.c</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> searches for the word while in all files ending in .c, in the current directory as well as all its subdirectories.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"><B>-w</B> match whole words</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> By default OGrep will match text regardless of where it appears.&nbsp; To make it only match entire words specify this switch.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">For example by default the regular expression 'abc' would match within both 'abc' and 'xabcy'. There are regular expression modifiers that can be used to make it match only 'abc' since in the other case abc occurs within another word. With this switch, OGrep automatically takes the match string and makes it into this type of regular expression. E.g, when the &lt;span</FONT><BR>
<BR>
<BR>
<FONT FACE="Arial" SIZE="2">By default OGrep will list each filename when it finds the first match within a file, then list each matching line underneath it. At the end it will show a count of the number of matches. But there are various command line options which can modify the format of the output.</FONT><BR>

<LI><FONT FACE="Arial" SIZE="2">-c list the file names matched, along with a count of matches&nbsp;</FONT>
<LI><FONT FACE="Arial" SIZE="2">-l list only the file names for files that have matches&nbsp;&nbsp;&nbsp;</FONT>
<LI><FONT FACE="Arial" SIZE="2">-n list the line number of matching lines next to the matching line</FONT>
<LI><FONT FACE="Arial" SIZE="2">-o (Unix format) list the file name and line number to the left of each matching line, instead of showing the file names separately.</FONT>
<LI><FONT FACE="Arial" SIZE="2">-v lines nonmatching lines instead of matching lines</FONT>
<LI><FONT FACE="Arial" SIZE="2">-z list the file names matched, line numbers, and matched lines</FONT><BR>
<FONT FACE="Arial" SIZE="2">&nbsp;&nbsp;
</FONT>
<BR><BR><BR>
<A NAME="hs410"></A>
<FONT FACE="Arial" COLOR="#0000FF" SIZE="5"><B>Regular Expressions</B></FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Regular expressions can be used as expressions within match-strings. They allow a more general mechanism for doing pattern-matches than having to specify each character specifically. For example, the '.' matches any character, so using the sequence 'a.c' would match any three character sequence starting with 'a' and ending with 'c'. This page discusses the various pattern matching mechanisms available when regular expression matching is enabled.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Because the pattern matching function of regular expressions uses characters to specify patterns, those characters can not be matched directly.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">For example '.' matches any character, but there may be instances when you want it to match only a period. To resolve this, the pattern matching symbols may be quoted by preceding them with the '\' character. This means that the pattern 'a\.b' matches only the sequence a.b.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Since the quote character generally means quote the next character, trying to match a quote character means the quote character itself has to be quoted. For example to match the text 'a\b' one one have to write the pattern 'a\\b'.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">The quote character is sometimes used to extend the working of the pattern matcher, for example the sequence \b does not mean a 'b' character is being quoted, it means match the beginning or ending of a word.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">The following symbols match various types of patterns:</FONT><BR>
<BR>

<LI><FONT FACE="Arial" SIZE="2">'.' match any character</FONT>
<LI><FONT FACE="Arial" SIZE="2">'*' match zero or more occurrances of the preceding character</FONT>
<LI><FONT FACE="Arial" SIZE="2">'+' match one or more occurrances of the preceding character</FONT>
<LI><FONT FACE="Arial" SIZE="2">'?' match zero or one occurrances of the preceding character</FONT>
<LI><FONT FACE="Arial" SIZE="2">'^' match the start of a line</FONT>
<LI><FONT FACE="Arial" SIZE="2">'$' match the end of a line</FONT>
<LI><FONT FACE="Arial" SIZE="2">'\b' match the beginning or ending of a word</FONT>
<LI><FONT FACE="Arial" SIZE="2">'\B' match within a word</FONT>
<LI><FONT FACE="Arial" SIZE="2">'\w' match the beginning of a word</FONT>
<LI><FONT FACE="Arial" SIZE="2">'\W' match the ending of a word</FONT>
<LI><FONT FACE="Arial" SIZE="2">'\&lt;' match the beginning, ending, or inside a word</FONT>
<LI><FONT FACE="Arial" SIZE="2">'\&gt;' match anything other than the beginning, ending, or inside a word</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Some of the basic pattern matching such as '+' can match multiple occurances of a character. Range Matching is a more general statement on the number of occurances of a character, for example you&nbsp; can match a bounded range, say from two to four 'a' characters by doing the following:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">OGrep "a\{2,4\}" *.c&nbsp;</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Brackets [] can be used to delimit a set of characters. Then the bracketed sequence will match any character in the set. For example</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">OGrep "[abc]" *.c</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">matches any of the characters a,b,c. A range of characters can be specified:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">OGrep "[a-m]" *.c</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">matches any characters in the range a-m.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Set negation is possible:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">OGrep "[^a-z]" *.c</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">matches anything but a lowercase letter.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Sets can be more complex:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">OGrep "[A-Za-z0-9]" *.c</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">matches any alphanumeric value.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Sets can be combined with more basic pattern matching:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">OGrep "[A-Z]?" *.c</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">matches zero or one upper case characters.</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">OGrep "[0-9]\{2,4\}"</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">matches from two to four digits.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Sometimes, it is desirable to match the same sub-pattern multiple times before having grep declare the pattern as a match for the text.&nbsp; In a simple case:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">OGrep "\(myword\)|\0" *.c&nbsp;</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">matches the string:</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">myword|myword</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">In this case the quoted parenthesis surround the region to match, and the \0 says match that region again. This is not a very interesting case, but when combined with other pattern matching it becomes more powerful, because the \0 doesn't reapply the pattern but instead matches exactly the same pattern as before. For example to combine it with a set:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">OGrep "\([a-z]+\)||\0" *.c&nbsp;</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">matches any lower-case word twice, as long as it is separated from itself by two | characters. This pattern would match 'ab||ab' but not 'ab||xy'.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Up to ten such regions may be specified in the pattern; to access them use \0 \1 \2 ... \9 where the digit gives the order the region is encountered within the pattern.
</FONT>
<BR><BR><BR>
<A NAME="hs420"></A>
<FONT FACE="Arial" COLOR="#0000FF" SIZE="5"><B>OLink</B></FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">OLink takes the output files from compilers and assemblers, and merges them together. This merging is necessary because often a single source file will either declare 'global' code or data that is accessible from other source files, or reference such global data from another file. Each output file from a compiler or assembler will have a list of these kinds of declarations, and the linker has two tasks: to combine the actual code and data from different files, and to resolve these global references between files.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">The end result of linking in most systems is to generate an executable file, however olink generates a fully linked object file (or sometimes a partially linked file) and generation of the executable is deferred to link post processor.&nbsp; The link post processor for Windows 32 bit programs is </FONT><A HREF="#hs540"><FONT FACE="Arial" SIZE="2">DLPE.EXE</FONT></A><FONT FACE="Arial" SIZE="2">.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">When it comes to the actual data being combined, the compiler or assembler will organize the code and data into sections. Each section has a name, and this name is one of the criteria used in combining section data. For example a code section might contain the code fragments from the file, an initialized data section might hold initialized data, and an uninitialized data section might reserve space for uninitialized data. In compiler output, other sections might occur for example to hold constant data, string data, or control information. An assembly program can directly control the segmentation of code and data into sections, and any number of arbitrary sections may appear according to the needs of the program.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">It should be stressed that OLink does not generate actual ROM images or executable files; all it does is combine code and data, and resolve the global references. Another post-processing program such as DLHEX or DLPE is used to generate the ROM image or executable file, based on the output of OLink.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">The output of OLink can beguided through use of a </FONT><A HREF="#hs440"><FONT FACE="Arial" SIZE="2">specification file</FONT></A><FONT FACE="Arial" SIZE="2"> and through command-line defines. The specification file indicates the ordering and grouping of sections, and gives default addresses and other attributes to the groupings. Command-line defines can be used to taylor the specifics of how the specification file is used; in OLink the command line defines generally act in terms of giving an absolute address to a variable which has been referenced elsewhere.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">The general form of an OLink </FONT><A HREF="#hs430"><FONT FACE="Arial" SIZE="2">Command Line</FONT></A><FONT FACE="Arial" SIZE="2"> is:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">OLink [options] filename-list</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Where filename-list gives a list of files to merge together.&nbsp; OLink natively understands files of the extension .o and .l, when these are generated by other tools in this package. Generally it will pass other files specified on the command line to a post-processing program for further analysis. For example .res (windows resource) files are passed on to DLPE to help it build the executable.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Olink takes the files in filename-list, and produces an output file .rel extension.&nbsp; The .rel files have the same format as the object files generated by the compiler or assembler, but are partially or fully linked.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"><A HREF="#hs440">Specification files</FONT></A><FONT FACE="Arial" SIZE="2"> give a flexible method for specifying how to merge sections from the various input files. They can specify what code and data be combined together, in what order, and what the address of code and data should be. A specification file uses three basic constructs, and each construct can be further clarified with attributes.&nbsp;</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">At the top level there can be one or more Partitions.&nbsp; Each partition may be relocated independently of other partitions.&nbsp;&nbsp;</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">A partition contains one or more Overlays.&nbsp; The overlays are independendent units of code or data, which are overlayed onto a common region of memory. The overlay mechanism can be used for example in systems that need to use bank-switching to extend the amount of memory available.&nbsp;</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">An overlay contains Regions, which simply specify the names of sections that should be combined together.&nbsp; The regions can be actual section names, or expressions containing</FONT><BR>
<FONT FACE="Arial" SIZE="2">section names. Normally a region would contain all sections matching the section name from all input files, but, a Region can be further clarified with a list of files that should be considered for inclusion. In this way different files with the same section can be combined into different overlays.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"><A HREF="#hs450">Target configurations</FONT></A><FONT FACE="Arial" COLOR="#800000" SIZE="2"> </FONT><FONT FACE="Arial" SIZE="2">specify the default mechanism for taking the linker output and creating a ROM image or executable file. Each target configuration specifies a linker</FONT><BR>
<FONT FACE="Arial" SIZE="2">specification file, a list of default definitions, and the name of a post-processing program such as DLHex to run to create the final output file. The specification files used with default target configurations are generic in nature, and make certain assumptions about the program; however some of the identifiers in such specification filse may refer to definitions made elsewhere. Those definitions are generally part of the target configuration, and may be modified through command-line options to make minor changes to the configuration.&nbsp;</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">For example, in WIN32 DLLs, the target file specifies the base address of the DLL in terms of a linker define statement, which may be redefined via the command line /D define switch to not collide with other DLLs and thus improve load time.
</FONT>
<BR><BR><BR>
<A NAME="hs430"></A>
<FONT FACE="Arial" COLOR="#0000FF" SIZE="5"><B>Command Line</B></FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">The general format of an OLink command line is:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">OLink [options] file-list</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">where file-list is an arbitrary list of input files.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">For example:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">OLink one.o two.o three.o</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">links several object files and makes an output file called one.rel.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">By default OLink takes the name of the first file on the command line, and replaces its extension with the extension .rel,to decide on an output file name.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">The file list can have wildcards:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">OLink /otest.rel *.o</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">links all the files in the curent directory, and the results are put in test.rel because the /o command line switch is specified.</FONT><BR>
<BR>
<BR>
<FONT FACE="Arial" SIZE="2">Response files can be used as an alternate to specifying input on the command line. For example:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">OLink @myresp.lst</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">will take command line options from 'myresp.lst'.&nbsp; This is useful for example when there are many .o or .l files being merged and it is not convenient to specify them on the command line.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Following is a list of the command line switches OLink supports.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">-c case sensitivity</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> By default OLink treats symbols as case-insensitive. If the -c+ switch is specified on the command line, labels will be treated as case sensitive. This supports certain language compilers that do allow the user to type the same word in different case, and have it mean different things.</FONT><BR>
<BR>
<BR>
<FONT FACE="Arial" SIZE="2"><B>-opath</B> Specifying the outpuf tile name</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> By default, OLink will take the first input file name, and replace it's extension with the extension .rel to create the name of the output file. However in some cases it is useful to be able to specify the output file name. The specified name can have its extension specified, or it can be typed without an extension to allow OLink to add the .rel extension.</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> OLink /r+ /omyfile test1.o test2.o test3.o cl.l</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> makes an object file called myfile.rel</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"><B>-Lpath</B> specify search path</FONT><BR>
<FONT FACE="Arial" SIZE="2"> By default, OLink will search for objecc and library files in the C Compiler library file path, and in the current directory. This option may be used to specify additional directories to search for lib files:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> OLink /L..\mylibs test.o floating.l&nbsp;</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> will find floating.l either in the C compiler library directory, the current directory, or the directory ..\mylibs.</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">-Ddefine=value</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> OLink allows definition of global variables on the command line, and gives them an absolute address. This facility can be used either to set the location of a function or data, or to provide a constant value to a </FONT><A HREF="#hs440"><FONT FACE="Arial" SIZE="2">specification file</FONT></A><FONT FACE="Arial" COLOR="#800000" SIZE="2"> </FONT><FONT FACE="Arial" SIZE="2">entry or even change a constant in user code.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> For example</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> OLink /DRAM=0x80000000 myprog.o</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> Defines a global variable RAM which has the address 80000000 hex. This variable may be accessed externally from either the program code, or the specification file. It might be used for example to relocate code or data, to specify the address of some hardware, to set a a link-time constant into the program, and so forth.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> Decimal values for addresses may be provided by omitting the 0x prefix.&nbsp;</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"><B>/r+</B> perform complete link</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> By default, OLink performs a partial link. In a partial link, some global definitions may remain unresolved, and libraries are ignored. The output file may be further linked with more object files or with the result of other partial links. However, a partial link cannot be used to generate a rom image or executable file, because not all the information required for such binaries has been generated; specifically there may be some addresses that haven't been defined yet.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> Usually, a complete link happens automatically when the /T switch is used to specify a </FONT><A HREF="#hs450"><FONT FACE="Arial" SIZE="2">target configuration</FONT></A><FONT FACE="Arial" SIZE="2">.&nbsp; However in some cases it is desirable to indicate to the linker that a complete link is desired without specifying a target configuration. Use /r+ for this purpose.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"><B>-m</B>&nbsp; generate map file</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> The map file name will be the same as the name of the .rel file, with the extension replaced by .map. The standard map file summarizes the partitions theprogram is contained in, and then lists publics in both alphabetic and numeric order.&nbsp;</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> A more detailed map file may be obtained by using /mx. This gives a list of partitions, overlays, regions, and files that went into making up the program, in the order they were included. t also includes details of the attributes used to place the sections.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"><B>-s</B> - use specification file</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> The </FONT><A HREF="#hs440"><FONT FACE="Arial" SIZE="2">specification file</FONT></A><FONT FACE="Arial" SIZE="2"> gives the layout of the program as it will exist in memory or in an executable file.&nbsp; Without a specification file, the linker will just order sections in the order it finds them, starting at address zero.&nbsp; Sometimes a default specification file will be selected automatically when using&nbsp; the /T&nbsp; </FONT><A HREF="#hs450"><FONT FACE="Arial" SIZE="2">target configuration</FONT></A><FONT FACE="Arial" SIZE="2"> switch. This specification file may be overridden with the /s switch; or if the /T switch is not specified the /s switch may be used to select a specification file. For example:</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> OLink /smyprog.spc myprog.o</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"><B>-T target configuration</B></FONT><BR>
<FONT FACE="Arial" SIZE="2"> The </FONT><A HREF="#hs450"><FONT FACE="Arial" SIZE="2">target configuration</FONT></A><FONT FACE="Arial" SIZE="2"> switch specifies that a specific profile be used to build the target. The profile includes a specification file, default definitions, a post-processing program to run, and some other information. The link will be done with the givenparameters, and then the post-processing program will be run to generate the final ROM image or executable file.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> For example:</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> </FONT><FONT FACE="Courier New" SIZE="2">OLink /T:M3 myprog.o</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> selects the specification profile that builds a Motorola Hex file with four-byte addresses.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"><B>-l</B> link only</FONT><BR>
<FONT FACE="Arial" SIZE="2"> Sometimes it is convenient to use the /T switch but it isn't necessary to go on to call the post processing program to generate a ROM image or executable.&nbsp; This switch stops the linker after the .rel file is generated.
</FONT>
<BR><BR><BR>
<A NAME="hs440"></A>
<FONT FACE="Arial" COLOR="#0000FF" SIZE="5"><B>Specification Files</B></FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">A specification file indicates the combination and ordering of sections of code and data. The specification file consists of one or more&nbsp; Partitions, which are independent units of code and/or data.&nbsp;</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Each partition holds one or more Overlays. Overlays are units of code and/or data which may share the same location in memory; for example a processor with a small memory address can use bank switching to move different units of code in and out of the address range as necessary. These different units of code would however all share the same address, so the overlay mechanism gives a way of relocating multiple units of code to the same address.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Each overlay holds one or more Regions; a region is what specifies which sections get combined. For example the region code takes all sections named code from the input file and concatenates them together. Multiple regions can be concatenated one after another within an overlay. To support the overlay mechanism, each region may further be qualified with file names, so that you can specify that sections named code from one group of files go in one region, and sections named code from another group of files go in another region. These regions could be placed in different overlays to help with things like the bank-switch mechanism indicated above.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Partitions, overlays, and regions can be given attributes to specify things like an absolute address, a maximum size, alignment, and so forth.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">You can also define labels within partitions and overlays similar to assignment statements in a high-level-language. Each label has an associated expression, which is calculated and then used as a value for the label. These values become globals to the linker, and are treated the same as the address obtained when declaring a global variable in the assembler and compiler. Code in the object files can referencethese labels as if they were externals.&nbsp;</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Further, expressions used in defining a label or attribute could use another label which is not defined in the specification file; this might be defined for examplesomewhere in the code, or in a command-line definition.&nbsp; It is especially useful to define such labels in a command line definition, as a way to customize the specification file without rewriting it. For example, if two peices of hardware share the same source code but are linked at different base addresses, one might write a single linker specification file, referencing the base address as a label. Then a linker command-line definition could be used to resolve the specific address the code is linked for.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">The following will be used as an example:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">partition</FONT><BR>
<FONT FACE="Courier New" SIZE="2">{</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> overlay {</FONT><BR>
<FONT FACE="Courier New" SIZE="2">&nbsp; region {} data [align=4];</FONT><BR>
<FONT FACE="Courier New" SIZE="2">&nbsp; region {} bss.</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> } RAM [addr=0x0000, size=0x4000];</FONT><BR>
<FONT FACE="Courier New" SIZE="2">} DATA;</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">partition</FONT><BR>
<FONT FACE="Courier New" SIZE="2">{</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> overlay {</FONT><BR>
<FONT FACE="Courier New" SIZE="2">&nbsp;&nbsp; region {} code;</FONT><BR>
<FONT FACE="Courier New" SIZE="2">&nbsp;&nbsp; region {} const;</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> } ROM;</FONT><BR>
<FONT FACE="Courier New" SIZE="2">} CODE [addr=0xf000, size=0x1000];</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">This defines two partitions, in this case one is for data nad one is for code. The first partition is named DATA and consists of two groups of sections.&nbsp; First all sections named data are concatenated together, then all sections named bss follow after that. This partition is defined with attributes to start address 0, and extend for 16K.&nbsp; If the actual size of the partition is greater than 16K, an error will be generated. In this case the overlay is named RAM; this overlay name is what is visible to ROM-generation tools such as DLHEX.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">The second partition is named CODE and also consists of two groups of sections; first all sections named codeare concatenated together, followed by all sections named const. This partition starts at address 0xf000, and extends for 4K. In this case the overlay name visible to DLHEX or other executable-generation tools is ROM.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">In the first partition, an align=4 attribute is declared on the data region. This means that each data section put into the region will be aligned on a four-byte boundary when it is loaded from its corresponding file. (Note: if assembly language code specifies a more stringent bound such as align = 8, that will be used instead).</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">In the following:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">partition</FONT><BR>
<FONT FACE="Courier New" SIZE="2">{</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> overlay {</FONT><BR>
<FONT FACE="Courier New" SIZE="2">&nbsp;&nbsp; region { bank1a.o bank1b.o bank1c.o } code;</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> } BANK1;</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> overlay {</FONT><BR>
<FONT FACE="Courier New" SIZE="2">&nbsp;&nbsp; region { bank2a.o bank2b.o bank2c.o } code;</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> } BANK2;</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> overlay {</FONT><BR>
<FONT FACE="Courier New" SIZE="2">&nbsp;&nbsp; region { bank3a.o bank3b.o bank3c.o } code;</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> } BANK3;</FONT><BR>
<FONT FACE="Courier New" SIZE="2">} CODE [addr = 0xe000, size = 0x1000];</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Three banks of code have been defined, each of which starts at address 0xe000 and extends for 4K. Each region references sections named code, however, file names are specifically specified for each region,&nbsp; so that only code sections from specific files will be included while processing the region. For example in the overlay BANK1, only files bank1a.o, bank1b.o, and bank1c.o will contributed to the contents of the region.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Wildcards may be used in the file specification, so that the above could be written:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">partition</FONT><BR>
<FONT FACE="Courier New" SIZE="2">{</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> overlay {</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">&nbsp;&nbsp; region { bank1*.o } code;</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> } BANK1;</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> overlay {</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">&nbsp;&nbsp; region { bank2*.o } code;</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> } BANK2;</FONT><BR>
<FONT FACE="Courier New" SIZE="2">&nbsp;</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> overlay {</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">&nbsp;&nbsp; region { bank3*.o } code;</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> } BANK3;</FONT><BR>
<FONT FACE="Courier New" SIZE="2">} CODE [addr= 0xe000, size = 0x1000];</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">In the following:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">partition</FONT><BR>
<FONT FACE="Courier New" SIZE="2">{</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> overlay {</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">&nbsp;&nbsp; RAMSTART=$</FONT><BR>
<FONT FACE="Courier New" SIZE="2">&nbsp;&nbsp; region {} data [align=4];</FONT><BR>
<FONT FACE="Courier New" SIZE="2">&nbsp;&nbsp; style="font-family: Courier New,Courier,monospace;"&gt;</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">&nbsp;&nbsp; region {} bss;</FONT><BR>
<FONT FACE="Courier New" SIZE="2">&nbsp;&nbsp;&nbsp; RAMEND=$</FONT><BR>
<FONT FACE="Courier New" SIZE="2">&nbsp; } RAM [addr=0x0000, size=0x4000];</FONT><BR>
<FONT FACE="Courier New" SIZE="2">} DATA;</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">The labels RAMSTART and RAMEND have been defined. The '$' in the expression indicates to use the address at the location the label is specified, so these definitions effectively define labels at the beginning and ending of the overlay. As indicated before these define global variables, so an x86 assembler program such as the following could be used to set all data in these regions to zero:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">extern RAMSTART, RAMEND</FONT><BR>
<FONT FACE="Courier New" SIZE="2">mov edi, RAMSTART</FONT><BR>
<FONT FACE="Courier New" SIZE="2">mov ecx,RAMEND-RAMSTART</FONT><BR>
<FONT FACE="Courier New" SIZE="2">mov al, 0</FONT><BR>
<FONT FACE="Courier New" SIZE="2">cld</FONT><BR>
<FONT FACE="Courier New" SIZE="2">rep stosb</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Expressions may be more complex, consisting of add, subtract, multiply,divide and parenthesis. As a simple example the above example can be rewritten to define a size:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">partition</FONT><BR>
<FONT FACE="Courier New" SIZE="2">{</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> overlay {</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">&nbsp;&nbsp; RAMSTART=$</FONT><BR>
<FONT FACE="Courier New" SIZE="2">&nbsp;&nbsp; region {} data [align=4];</FONT><BR>
<FONT FACE="Courier New" SIZE="2">&nbsp;&nbsp; region {} bss;</FONT><BR>
<FONT FACE="Courier New" SIZE="2">&nbsp;&nbsp;&nbsp; RAMSIZE = $-RAMSTART</FONT><BR>
<FONT FACE="Courier New" SIZE="2">&nbsp; } RAM [addr=0x0000, size=0x4000];</FONT><BR>
<FONT FACE="Courier New" SIZE="2">} DATA;</FONT><BR>
<BR>
<BR>
<BR>
<FONT FACE="Arial" SIZE="2">Labels or expressions may be used in attributes, for example:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">partition</FONT><BR>
<FONT FACE="Courier New" SIZE="2">{</FONT><BR>
<FONT FACE="Courier New" SIZE="2"> overlay {</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">&nbsp;&nbsp; RAMSTART=$</FONT><BR>
<FONT FACE="Courier New" SIZE="2">&nbsp;&nbsp; region {} data [align=4];</FONT><BR>
<FONT FACE="Courier New" SIZE="2">&nbsp;&nbsp; region {} bss.</FONT><BR>
<FONT FACE="Courier New" SIZE="2">&nbsp;&nbsp;&nbsp; RAMSIZE = $-RAMSTART</FONT><BR>
<FONT FACE="Courier New" SIZE="2">&nbsp; } RAM [addr=RAMBASE, size=0x4000];</FONT><BR>
<FONT FACE="Courier New" SIZE="2">} DATA;</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Here the base address is defined in terms of a label RAMBASE. But RAMBASE is not defined anywhere in the specification file, so it has to be pulled from the linker's table of globals. In this case we might define it on the linker command line as follows:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">OLink /DRAMBASE=0x7000 /smyspec.spc ...</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Labels don't have to include '$' in the expression, although it is often useful. For example:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">MYLABEL=0x44000+2000&nbsp;</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">is valid.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Note that when using target configurations, the default specificationfiles use these types of declarations, but the target configuration gives default values to use. For example the default value for RAMBASE in a hex file is 0x10000, when used with the default linker specification file that is used for binary and hex file output. But such values can be overridden on the command line; if it is desirable to use the default specification file but RAMBASE is 0x8000 for the specific hardware in question one might use OLink as follows:&nbsp;</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">OLink /T:M3 /DRAMBASE=0x8000 ...</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Partitions, overlays, and regions can be attributed with one or more attributes. The attributes are comma delimited, and enclosed in braces. They occur after the name of the partition or overlay, or after the section specified by a region.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">The possible attributes are listed in Table 1</FONT><BR>
<center>
<table border="1" cellpadding="2" cellspacing="2">
  <tbody>
<BR>

    <tr>
      <td style="vertical-align: top;">Attribute</td>
      <td style="vertical-align: top;">Meaning</td>
      <td style="vertical-align: top;">Default Value for Partitions</td>
      <td style="vertical-align: top;">Default Value for Overlays</td>
      <td style="vertical-align: top;">Default Value for Regions</td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top;">ADDR</td>
      <td style="vertical-align: top;">Address</td>
      <td style="vertical-align: top;">0, or end of previous partition</td>
      <td style="vertical-align: top;">partition address</td>
      <td style="vertical-align: top;">overlay address or end of previous region</td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top;">SIZE</td>
      <td style="vertical-align: top;">Absolute size</td>
      <td style="vertical-align: top;">unassigned</td>
      <td style="vertical-align: top;">partition size</td>
      <td style="vertical-align: top;">unassigned</td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top;">MAXSIZE</td>
      <td style="vertical-align: top;">absolute size may vary up to this amount</td>
      <td style="vertical-align: top;">unassigned</td>
      <td style="vertical-align: top;">partition maxsize</td>
      <td style="vertical-align: top;">unassigned</td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top;">ROUNDSIZE</td>
      <td style="vertical-align: top;">absolute size may vary, but will be rounded up to the next multiple of this</td>
      <td style="vertical-align: top;">1</td>
      <td style="vertical-align: top;">partition roundsize</td>
      <td style="vertical-align: top;">unassigned</td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top;">FILL</td>
      <td style="vertical-align: top;">fill value used when absolute size does not match size of data included in region</td>
      <td style="vertical-align: top;">0</td>
      <td style="vertical-align: top;">partition fill</td>
      <td style="vertical-align: top;">overlay fill</td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top;">ALIGN</td>
      <td style="vertical-align: top;">minimum alignment of region</td>
      <td style="vertical-align: top;">1</td>
      <td style="vertical-align: top;">partition alignment</td>
      <td style="vertical-align: top;">overlay alignment</td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top;">VIRTUAL</td>
      <td style="vertical-align: top;">base address for linking the region, when base address does not match the ADDR attribute</td>
      <td style="vertical-align: top;">unassigned</td>
      <td style="vertical-align: top;">partition virtual attribute</td>
      <td style="vertical-align: top;">virtual address of overlay, or end of previous region</td>
    </tr>
<BR>

  </tbody>
</table>
<BR>
<BR>
<FONT FACE="Arial" SIZE="2">Table 1.&nbsp; List of attributes</center>
</FONT><BR>
<BR>
<BR>
<BR>
<FONT FACE="Arial" SIZE="2">Usually the region statement is used to specify a specific section name such as code:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">region { } code;</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">But sometimes it is useful to be able to combine multiple sections in a single region with the or operator</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">region {} code | const;</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">However this is different making two regions, one for code and one for const. The difference is that in this case code and const regions may be intermixed; whereas in the other case all the code sections would be combined together, separately from all the const regions.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Wildcards may be used in the region name:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">region {} code*</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">matches the sections name code1, code2, code123, and so forth.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">And for example</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">region {} *&nbsp;</FONT><FONT FACE="Arial" SIZE="2">&nbsp;</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">matches ALL sections. There are two wildcard characters: * matches a sequence of characters, whereas ? matches a single character.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Other times you want to do a catch all which gets all sections except for a select section or group of sections.</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">region {} *&amp; !(code*)</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">This uses the and operator and the not operator to select all sections which do not start with the four letters 'code'.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">A region can be named with any potentially complex expression involving section names and these operators, to match various combinations of sections.
</FONT>
<BR><BR><BR>
<A NAME="hs450"></A>
<FONT FACE="Arial" COLOR="#0000FF" SIZE="5"><B>Target Configurations</B></FONT><BR>
<BR>
<BR>
<FONT FACE="Arial" SIZE="2">OLink has several default target configurations, that associate the various data needed for creating linker output for a particular type of output together. Each target configuration includes a linker </FONT><A HREF="#hs440"><FONT FACE="Arial" SIZE="2">specification file</FONT></A><FONT FACE="Arial" SIZE="2">, default definitions for items used but not declared in the specification file, and a reference to a post-processing tool that will take an image linked against the specification file and generate some final binary image, such as a ROM image or an Operating System executable.&nbsp;</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Each target configuration is accessible via the /T linker switch.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">For example:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">OLink /T:BIN test.o</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">invokes the target configuration associated with the name BIN. In the case of BIN the file is linked into three partitions; code, data and stack using the specification file hex.spc;</FONT><BR>
<FONT FACE="Arial" SIZE="2">and the results are dumped to a binary file using DLHex.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">The remainder of this section will discuss the default target configurations rather than the mechanism for defining them.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">There are several output file formats for generating a rom-based image. However, they all use a common specification file and post-processing tool. This section will briefly touch on the available output formats then touch on the specification file in more detail.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">The available output formats in this mode are:</FONT><BR>

<LI><FONT FACE="Arial" SIZE="2">/T:M1 Motorola srecord file format, 2 byte addresses</FONT>
<LI><FONT FACE="Arial" SIZE="2">/T:M2 Motorola srecord file format, 3 byte addresses</FONT>
<LI><FONT FACE="Arial" SIZE="2">/T:M3 Motorola srecord file format, 4 byte addresses</FONT>
<LI><FONT FACE="Arial" SIZE="2">/T:I1 Intel hex file format, 16 bits</FONT>
<LI><FONT FACE="Arial" SIZE="2">/T:I2 Intel hex file format, segmented</FONT>
<LI><FONT FACE="Arial" SIZE="2">/T:I4 Intel hex file format, 32 bits</FONT>
<LI><FONT FACE="Arial" SIZE="2">/T:BIN Binary file format</FONT>
<LI><BR>
<BR>
<FONT FACE="Arial" SIZE="2">The default specification file for these output formats is hex.spc, and the default post-processing tool is dlhex.exe.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Hex.spc has 4 independent overlays for code and data. Table 1 lists the overlays, the section names that are recognized in each overlay. It also lists an identifier that can be used with the /D command line switch to the linker to adjust base addresses, and the default base address for each overlay.</FONT><BR>
<center>
<table border="1" cellpadding="2"  cellspacing="2">
  <tbody>
<BR>

    <tr>
      <td style="vertical-align: top; font-weight: bold;">Overlay</td>
      <td style="vertical-align: top; font-weight: bold;">Sections</td>
      <td style="vertical-align: top; font-weight: bold;">Base Address Identifier</td>
      <td style="vertical-align: top; font-weight: bold;">Base Address</td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top;">RESET</td>
      <td style="vertical-align: top;">reset</td>
      <td style="vertical-align: top;">RESETBASE</td>
      <td style="vertical-align: top;">0x00000</td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top;">ROM</td>
      <td style="vertical-align: top;">code, const, string</td>
      <td style="vertical-align: top;">CODEBASE</td>
      <td style="vertical-align: top;">0x00008</td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top;">RAM</td>
      <td style="vertical-align: top;">data, bss</td>
      <td style="vertical-align: top;">RAMBASE</td>
      <td style="vertical-align: top;">0x10000</td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top;">STACK</td>
      <td style="vertical-align: top;">stack</td>
      <td style="vertical-align: top;">STACKBASE (size = STACKSIZE)</td>
      <td style="vertical-align: top;">0x20000 ( 0x400)</td>
    </tr>
<BR>

  </tbody>
</table>
<BR>
<BR>
<BR>
<FONT FACE="Arial" SIZE="2">Table 1 - Hex.spc details</center>
</FONT><BR>
<BR>
<BR>
<BR>
<FONT FACE="Arial" SIZE="2">Several types of WIN32 images may be generated. These include:</FONT><BR>

<LI><FONT FACE="Arial" SIZE="2">/T:CON32 - console application</FONT>
<LI><FONT FACE="Arial" SIZE="2">/T:GUI32 - windowing application</FONT>
<LI><FONT FACE="Arial" SIZE="2">/T:DLL32 - dll application</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">The default specification file for these output formats is pe.spc, and the default post-processing tool is dlpe.exe. PE.spc has two independent overlays for code and data. Table 2 lists the</FONT><BR>
<FONT FACE="Arial" SIZE="2">overlays, and the section names that are recognized in each overlay. Table 3 lists the various values supported by pe.spc and&nbsp; dlpe.exe that may be adjusted on the linker command line.</FONT><BR>
<BR>
<center>
<table border="1" cellpadding="2"  cellspacing="2">
  <tbody>
<BR>

    <tr>
      <td style="vertical-align: top; font-weight: bold;">Overlay</td>
      <td style="vertical-align: top; font-weight: bold;">Sections</td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top;">.text</td>
      <td style="vertical-align: top;">code, const</td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top;">.data</td>
      <td style="vertical-align: top;">data, string, bss</td>
    </tr>
<BR>

  </tbody>
</table>
<BR>
<BR>
<FONT FACE="Arial" SIZE="2">Table 2 - PE.SPC overlays</center>
</FONT><BR>
<BR>
<BR>
<center>
<table border="1" cellpadding="2" cellspacing="2">
  <tbody>
<BR>

    <tr>
      <td style="vertical-align: top;">Definition</td>
      <td style="vertical-align: top;">Meaning</td>
      <td style="vertical-align: top;">Default</td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top;">FILEALIGN</td>
      <td style="vertical-align: top;">Object Alignment within an executable file</td>
      <td style="vertical-align: top;">0x200</td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top;">HEAPCOMMIT</td>
      <td style="vertical-align: top;">Amount of local heap to commit at program start</td>
      <td style="vertical-align: top;">0</td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top;">HEAPSIZE</td>
      <td style="vertical-align: top;">Size of local heap</td>
      <td style="vertical-align: top;">0x100000</td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top;">IMAGEBASE</td>
      <td style="vertical-align: top;">Base address for the image (used to resolve DLL Address collisions)</td>
      <td style="vertical-align: top;">0x400000</td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top;">OBJECTALIGN</td>
      <td style="vertical-align: top;">Object alignmed t in memory</td>
      <td style="vertical-align: top;">0x1000</td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top;">STACKCOMMIT</td>
      <td style="vertical-align: top;">Amount of stack to commit at program start</td>
      <td style="vertical-align: top;">0x2000</td>
    </tr>
<BR>

    <tr>
      <td style="vertical-align: top;">STACKSIZE</td>
      <td style="vertical-align: top;">Size of stack for default thread</td>
      <td style="vertical-align: top;">0x100000</td>
    </tr>
<BR>

  </tbody>
</table>
<BR>
<BR>
<FONT FACE="Arial" SIZE="2">Table 3 - PE.SPC adjustable parameters</center>
</FONT><BR>
<BR>
<BR>
<BR>
<BR>
<BR>
<BR>
<BR>
<BR>
<FONT FACE="Arial" SIZE="2">&gt;</FONT><BR>

<BR><BR><BR>
<A NAME="hs460"></A>
<FONT FACE="Arial" COLOR="#0000FF" SIZE="5"><B>OMake</B></FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">OMake currently has no documentation. OMake is however very similar to GNU make and the GNU make documentation is a good start.&nbsp;&nbsp; But it should be stressed that OMake is not GNU make and there may be incompatibilities.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">One known incompatibility is that OMake is case sensitive, even though it is being hosted on MSDOS/Windows.&nbsp; This is a problem when specifying file names if the file name is not spelled in exactly the same case the OS spells it.&nbsp;&nbsp;</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">This may be fixed in a future version.
</FONT>
<BR><BR><BR>
<A NAME="hs470"></A>
<FONT FACE="Arial" COLOR="#0000FF" SIZE="5"><B>OCPP</B></FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">OCPP is an extended version of the traditional C language preprocessor. The extensions include support for C11 and C99,&nbsp; It is beyond the</FONT><BR>
<FONT FACE="Arial" SIZE="2">scope of this document to discuss the format of input files used with the preprocessor. See a discussion of the C language for further</FONT><BR>
<FONT FACE="Arial" SIZE="2">details of use with the C language.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Note that OCPP is not quite the same as the preprocessor built into a C compiler. The C compiler is able to maintain a slightly more detailed context about the preprocessed text. In rare cases loss of this information will cause a file preprocessed with OCPP to not be compilable with any C compiler.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">The general form of an OCPP command line is:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">OCPP [options] file&nbsp;</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Here the file is the file to preprocess. (multiple files may be specified onthe command line if you choose).</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">OCPP has no mechanism for specifying the output file name; instead it takes the</FONT><BR>
<FONT FACE="Arial" SIZE="2">input file, strips the extension, and writes a file with a '.i' extension to indicate preprocessor output.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">There are several command line options that control how the preprocessing is done. These include the ability to enable extensions, the ability to set a path for include files, and options to define and undefine preprocessor variables.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Following is a list of the command line switches OCPP supports.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"><B>-A</B> strict mode</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> By default, OCPP will perform as a C89 version preprocessor, which is slightly looser than the standard. It can be tightened to meet the</FONT><BR>
<FONT FACE="Arial" SIZE="2">standard with the /A switch.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"><B>-1</B> C11 mode</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> Puts OCPP into the C11 parsing mode</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">-9 C99 mode</FONT><BR>
<FONT FACE="Arial" SIZE="2"> Puts OCPP into the C99 parsing mdoe</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">-I set include file path</FONT><BR>
<FONT FACE="Arial" SIZE="2"> By default, OCPP will use the C language system include path to search for include files specified in the source file. If there are other include paths OCPP should search, this switch can be specified to have it search them. For example by default the statement:</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> #include &lt;windows.h&gt;</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> will search in the C language system include directory to find windows.h.</FONT><BR>
<FONT FACE="Arial" SIZE="2"> Whereas:</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> OCPP /I.\include test.c</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> will create a file test.i, which will additionally search the path.\include for any include files specified in preprocessor directives.</FONT><BR>
<BR>
<BR>
<FONT FACE="Arial" SIZE="2"><B>/E[+-]nn</B> error control</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> nn is the maximum number of errors before the&nbsp; compile fails; if + is specified extended warnings will be shown that are normally disabled by default. If - is specified warnings will be turned off.&nbsp; For example:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> OCC /E+44 myfile.c</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> enables extended warnings and limits the number of&nbsp; errors to 44. By default only 25 errors will be shown and then the compiler will abort and</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> OCC /E- myfile.c</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> compiles myfile.c without displaying any warnings.</FONT><BR>
<BR>
<BR>
<BR>
<FONT FACE="Arial" SIZE="2">OCPP has two switches useful for defining preprocessor macros. The first switch /D defines a macro. The second switch /U causes OCPP to never allow the specified variable to be defined.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> For example</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> OCPP /DMYINT=4 test.c</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> defines the variable MYINT and gives it a value of 4. Whereas</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> OCPP /UMYINT test.c</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> globally undefines MYINT in such a way that it cannot be defined while preprocessing the file.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> A macro doesn't have to be defined with a value:</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> OCPP /DWIN32 test.c</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> might be used to specify preprocessing based on the program looking for the word WIN32 in #ifdef statements.</FONT><BR>
<BR>

<BR><BR><BR>
<A NAME="hs480"></A>
<FONT FACE="Arial" COLOR="#0000FF" SIZE="5"><B>OImpLib</B></FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">OImpLib is a WIN32 import librarian, suitable for various operations regarding the import sections of DLLs. It can take input from one of several sources, and place output in one of several destinations.In its most basic format one could use it to take a .DEF file or .DLL file and construct an import library for use with the toolchain, but it can also be used to create a .DEF file or extract things from a library.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">The general format of an OImpLib command line is:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">OImpLib [options] source dest</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">where source and dest specify files to use, and further, by parsing the extensions of source and dest OImpLib is able to act in one of several modes</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Response files can be used as an alternate to specifying input on the command line. For example:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">OImpLib test.l @myresp.lst</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">will take command line options from myresp.lst.&nbsp; In general it isn't necessary to use response files with OImpLib as the amount of input required is minimal.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Following is a list of command line switches OImpLib supports.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"><B>-c-</B>&nbsp; case insensitive import library</FONT><BR>
<FONT FACE="Arial" SIZE="2"> OImpLib will allow the creation of case insensitive libraries with this switch however, in general it isn't a good idea to make a case-insensitive import library, as WIN32 export records found in DLLs are case-sensitive.</FONT><BR>
<BR>
<BR>
<FONT FACE="Arial" SIZE="2">OImpLib will perform different operations depending on what the file extensions of the input files are. The output file is specified first, followed by one or more input files. The output file may be one of the following:&nbsp;</FONT><BR>

<LI><FONT FACE="Arial" SIZE="2">a library file</FONT>
<LI><FONT FACE="Arial" SIZE="2">an object file</FONT>
<LI><FONT FACE="Arial" SIZE="2">a .DEF file</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">When the output file is a library file, the input file can be a list of object files, .DEF files, and .DLL files. The object files will be placed in the library, whereas the export sections of .DEF and .DLL files will be converted to object files that hold import records, and then placed in the library.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">When the output file is an object file, a single input file can be either a .DEF or .DLL file. The exports from the input file will be placed in the output file.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">When the output file is a .DEF file, the input file can be either a .DLL file or an object file. The exports in the .DLL file will be written to the .DEF file, or the import records in the object file will be converted to export records and written to the .DEF file. For example:</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> </FONT><FONT FACE="Courier New" SIZE="2">OImpLib test.l kernel32.dll</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> will make an import library holding the export definitions from kernel32.dll</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> OImpLib test.ld mydll.def</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> will make an import library containing the export definitions from mydll.def.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> On the other hand:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> OImpLib user32.def user32.dll</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> will create a definition file from the export records in user32.dll
</FONT>
<BR><BR><BR>
<A NAME="hs490"></A>
<FONT FACE="Arial" COLOR="#0000FF" SIZE="5"><B>OLib</B></FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">OLib is an object file librarian. It is used to combine a group of object files into a single file, to make it easier to operate on the group of files. It is capable of adding, removing, and extracting object files from a static library.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">The general format of an OLib command line is:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">OLib [options] library object-file-list</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">where library specifies the library, and object-file-list specifies the list of files to operate on.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">For example:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">OLib test.l + obj1.o obj2.o obj3.o obj4.o obj5.o</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">adds several object files to the library test.l.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">The object file list can have wildcards:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">OLib test.l + *.o</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">adds all the object files from the current directory.</FONT><BR>
<BR>
<BR>
<FONT FACE="Arial" SIZE="2">Response files can be used as an alternate to specifying input on the command line. For example:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">OLib test.l @myresp.lst</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">will take command line options from myresp.lst.&nbsp; Response files might be used for example if a library is to be made out of dozens of object files, and they won't all fit on the OS command</FONT><BR>
<FONT FACE="Arial" SIZE="2">line.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Following is a list of the command line switches OLib supports.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"><B>/c-</B> case insensitivity</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> By default OLib makes case-sensitive libraries, but this switch will allow creation of a case-insensitive library.&nbsp; In general you don't need to make a library case insensitive, as the linker will handle case insensitivity based on command line switches even if the library is case-sensitive.</FONT><BR>
<BR>
<BR>
<FONT FACE="Arial" SIZE="2">In a previous examples the '+' symbol was used to indicate that the following files should be added to the library. '+' doesn't have to be used in this case because the default is to add files to the library. But there are two other command line modifiers that can be used to extract files from the library and remove files from the library. These are '*' for extract and '-' for remove. Note</FONT><BR>
<FONT FACE="Arial" SIZE="2">that '-' is also used for command line switches; to prevent it from being ambiguous it must be present with spaces on either side when used. The '+' and '-' and '*' can be mixed on the command line; files after one of these modifies will be processed according to that modifier until another modifier is encountered. For example:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">OLib test.l * obj1.o</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">extracts obj1.o from the library and places it in the current directory, and&nbsp;</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">OLib Test.l - obj2.o&nbsp;</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">removes obj2.o from the library and destroys it. As a more complex example:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">OLib test.l + add1.o add2.o - rem1.o rem2.o * ext1.o</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">adds the files add1.o and add2.o, removes the files rem1.o and rem2.o, and extracts the file ext1.o. The order of the modifiers in this example is arbitrary, and modifiers can occur more than once on the command line or in the response file.
</FONT>
<BR><BR><BR>
<A NAME="hs500"></A>
<FONT FACE="Arial" COLOR="#0000FF" SIZE="5"><B>ORC</B></FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">ORC is a windows resource compiler. It handles compilation of a file containing standard windows resources into a .RES file.&nbsp; The .RES file can be given to the linker or to DLPE for use in adding resources to a windows executable file. The specification for the format of the input file is mostly beyond the scope of this document other than to say that the ORC program has a C</FONT><BR>
<FONT FACE="Arial" SIZE="2">language preprocessor. This makes it possible to define symbolic constants.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">The general format of an ORC command line is:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">ORC [options] rcfile.rc</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">where rcfile.rc is the resource file to compile.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">At present ORC will not directly modify an EXE file but its output must be passed to the linker or post processing program.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Response files can be used as an alternate to specifying input on the command line. For example:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">ORC @myresp.lst&nbsp;</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">will take command line options from myresp.lst. In general it isn't necessary to use response files with ORC as the amount of input required is minimal.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Following is a list of command line switches ORC supports.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"><B>/ipath</B> set include file path</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> By default, ORC will use the C language header include path as an include path to search for files specified in preprocessor INCLUDE directives. For example the statement:</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> #include &lt;windows.h&gt;</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> will result in windows.h being found in the compiler include directory, and included in the file. If there are other paths that should be searched, they may be specified on the command line with the /i switch. For example:</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> </FONT><FONT FACE="Courier New" SIZE="2">ORC /i.\include test.rc&nbsp;</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> Searches in the directory .\include as well as in the C language include directory.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> The ORC preprocessor defines the preprocessor symbol RC_INVOKED to allow include files to specify sections that won't be evaluated by ORC. For example the windows headers use this to prevent RC compilers from trying to parse structure definitions written in the C language. This way instructions to the RC compiler can be intermixed with instructions to the C compiler without causing ORC to process things it isn't capable of processing.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"><B>/Ddefine=value</B></FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> Defines preprocessor macros.&nbsp; For example:</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> </FONT><FONT FACE="Courier New" SIZE="2">ORC /DMYINT=4 test.c</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> defines the macro MYINT and gives it a value of 4.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> A macro doesn't have to be defined with a value:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> ORC /DWIN32 test.c</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> might be used to specify preprocessing based on the program looking for the word WIN32 in #ifdef statements.
</FONT>
<BR><BR><BR>
<A NAME="hs510"></A>
<FONT FACE="Arial" COLOR="#0000FF" SIZE="5"><B>DLHex</B></FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">DLHex is a linker postprocessor for obtaining hex and binary files of the type used in generatring rom-based images for embedded systems. It can be used indirectly as part of the link process, if the default linker settings are sufficient. In many cases though configuring the output for an embedded system will require a customized linker specification file. The linker documentation&nbsp; discusses this in more detail. If a customized specification file is used, it may be necessary to call DLHex directly to obtain an output file.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">DLHex can produce output in one of several formats. These include&nbsp;</FONT><BR>

<LI><FONT FACE="Arial" SIZE="2">Motorola S19 files</FONT>
<LI><FONT FACE="Arial" SIZE="2">Intel Hex files</FONT>
<LI><FONT FACE="Arial" SIZE="2">pure binary output format</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">The S19 and Hex file formats are suitable for use with an EEProm burner or other device that can accept them; the binary format is available to make postprocessing the output for other types of requirements easier. In rare cases the binary format may be used directly, e.g. if a device has a file system and a suitable loader is written to load it into memory.</FONT><BR>
<BR>
<BR>
<FONT FACE="Arial" SIZE="2">The general form of a DLHex command line is:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">dlhex [options] relfile</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Here the rel file is the linker generated file that holds the completely linked code. There are several command line options that control the output. These include options for specifying what parts of the input file to process, how to format the output, and optionally a file name to use for the output file.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">The linker has a default linker specification file, which is used if the linker /T switch is used to run dlhex to create an outputfile. The script is as follows:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">partition {</FONT><BR>
<FONT FACE="Courier New" SIZE="2">&nbsp; overlay {</FONT><BR>
<FONT FACE="Courier New" SIZE="2">&nbsp;&nbsp; region {} reset [ size = RESETSIZE];</FONT><BR>
<FONT FACE="Courier New" SIZE="2">&nbsp; } RESET;</FONT><BR>
<FONT FACE="Courier New" SIZE="2">} pt0 [addr = RESETBASE];</FONT><BR>
<FONT FACE="Courier New" SIZE="2">partition {</FONT><BR>
<FONT FACE="Courier New" SIZE="2">&nbsp; overlay {</FONT><BR>
<FONT FACE="Courier New" SIZE="2">&nbsp;&nbsp; region {} code [ align = 2];</FONT><BR>
<FONT FACE="Courier New" SIZE="2">&nbsp;&nbsp; region {} const [ align = 4];</FONT><BR>
<FONT FACE="Courier New" SIZE="2">&nbsp;&nbsp; region {} string [ align = 2];</FONT><BR>
<FONT FACE="Courier New" SIZE="2">&nbsp; } ROM;</FONT><BR>
<FONT FACE="Courier New" SIZE="2">} pt1 [addr=CODEBASE];</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">partition {</FONT><BR>
<FONT FACE="Courier New" SIZE="2">&nbsp; overlay {</FONT><BR>
<FONT FACE="Courier New" SIZE="2">&nbsp;&nbsp; RAMDATA = $;</FONT><BR>
<FONT FACE="Courier New" SIZE="2">&nbsp;&nbsp; region {} data [ align = 4];</FONT><BR>
<FONT FACE="Courier New" SIZE="2">&nbsp;&nbsp; region {} bss [ align = 4];</FONT><BR>
<FONT FACE="Courier New" SIZE="2">&nbsp; } RAM ;</FONT><BR>
<FONT FACE="Courier New" SIZE="2">} pt2 [addr=RAMBASE];</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">partition {</FONT><BR>
<FONT FACE="Courier New" SIZE="2">&nbsp; overlay {</FONT><BR>
<FONT FACE="Courier New" SIZE="2">&nbsp;&nbsp; region {} stack[size = $400];</FONT><BR>
<FONT FACE="Courier New" SIZE="2">&nbsp;&nbsp; STACKPOINTER = $;</FONT><BR>
<FONT FACE="Courier New" SIZE="2">&nbsp; } STACK;</FONT><BR>
<FONT FACE="Courier New" SIZE="2">} pt3 [addr = STACKBASE];</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">From the above you can see it has four overlay sections, which are named 'RESET','ROM', 'RAM' and 'STACK'.&nbsp; In this case you may not want to extract the stack into an output file,</FONT><BR>
<FONT FACE="Arial" SIZE="2">since an embedded system might initialize it in a loop. It may or may not be useful to extract the RAM section either, depending on whether the design of the embedded system specifies initialized data. Assuming it is useful, the /c switch can be used to extract the RESET, ROM and RAM files into a single .HEX file like this:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">dlhex /cRESET,ROM,RAM /mM1 test.rel</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">or it can be used to extract the ROM and RAM sections into two files by running it twice like this:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">dlhex /cROM /mM1 /orom.S19 test.rel</FONT><BR>
<FONT FACE="Courier New" SIZE="2">dlhex /cRAM /mM1 /oram.S19 test.rel</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Note that the above discussions assumes use of default linker files; it is acceptable to use a customized linker specification file and name overlays</FONT><BR>
<FONT FACE="Arial" SIZE="2">anything desirable.</FONT><BR>
<BR>
<BR>
<FONT FACE="Arial" SIZE="2">Following is a list of command line switchs DLHex supports.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"><B>/c</B> - specify what overlays to use</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> The input file is a linker generated .rel file. Encoded in the input file is the program text, separated into the overlays indicated in the linker specification script. This command line option is used to specify which of these overlays will be placed in the output file. Following it overlay names are specified, separated by a comma. For example:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> dlhex /mM1 /cCODE;DATA test.rel</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> pulls the two overlays CODE and DATA from the test.rel file, and places the contents in a Motorola S19 file. By default, if no /c switch is specified, all overlays will be pulled from the .rel file in the order specified.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"><B>/oname</B> - specify output file</FONT><BR>
<FONT FACE="Arial" SIZE="2"> By default, DLhex will take the input file name, and replace the extension with an extension indicating what type of output is being used. These extensions are as follows:</FONT><BR>

<LI><FONT FACE="Arial" SIZE="2">BIN - a binary output file</FONT>
<LI><FONT FACE="Arial" SIZE="2">S19 - a Motorola S19 file</FONT>
<LI><FONT FACE="Arial" SIZE="2">HEX - an Intel Hex file</FONT><BR>
<FONT FACE="Arial" SIZE="2">&nbsp;&nbsp;</FONT><BR>
<FONT FACE="Arial" SIZE="2"> However in some cases it is useful to be able to specify the output file name with this switch. The specified name can have its extension specified,or it can be typed without an extension to allow DLhex to add one of the default extensions. For example:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> dlhex /mM1 /omyfile.dat test.rel</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> creates a Motorola S19 file and stores it in myfile.dat.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> Whereas</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> dlhex /mM1 /omyfile test.rel</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> creates&nbsp; a Motorola S19 file and stores it in myfile.S19.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"><B>/mxxx</B> -- specify output file format</FONT><BR>
<FONT FACE="Arial" SIZE="2">&nbsp; DLHex supports several types of Motorola S19 output files, several types of Intel Hex output files, and a binary output file format. This switch can be followed by one of the following specifiers:</FONT><BR>
<BR>

<LI><FONT FACE="Arial" SIZE="2"> M1 - Motorola S19 files with two byte address fields&nbsp;</FONT>
<LI><FONT FACE="Arial" SIZE="2"> M2 - Motorola S19 files with three byte address fields</FONT>
<LI><FONT FACE="Arial" SIZE="2"> M3 - Motorola S19 files with four-byte address fields</FONT>
<LI><FONT FACE="Arial" SIZE="2"> I1 - 16 bit Intel hex file. Can be segmented or not depending on the input.</FONT>
<LI><FONT FACE="Arial" SIZE="2"> I2 - 16 bit Intel hex file. Starts with a segmentation record.</FONT>
<LI><FONT FACE="Arial" SIZE="2"> I4 - 32 bit Intel hex file.</FONT>
<LI><FONT FACE="Arial" SIZE="2"> B - Binary output format</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> For practical purposes the I1 and I2 formats are the same, except the first record of an I2 file is guaranteed to be a segmentation record.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> The default output format if no /m switch is specified is the binary format.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"><B>/p:xx</B> - pad</FONT><BR>
<FONT FACE="Arial" SIZE="2"> By default DLHex does not pad output files. In the case of Motorola S19 and Intel Hex files there are address bytes in the output file, which means padding may be applied&nbsp; xternally if necessary, e.g.by an EPROM programmer. In the case of the binary format, no address bytes exist, and without padding the input files are copied directly to the binary output file one section at a time, without regard for the fact that it may be useful to align subsequent sections at the appropriate place relative to the first section. In other words, the default for the binary format is to create a file that has sections offset from each other based on their actual size, rather than based on the addressing information the linker has provided.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> This switch may be used to specify that padding is required between sections.&nbsp; the 'xx' value is a hexadecimal value used as the padding byte.</FONT><BR>
<FONT FACE="Arial" SIZE="2"> For example:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2"> dlhex /p:FF test.rel</FONT><BR>

<BR><BR><BR>
<A NAME="hs520"></A>
<FONT FACE="Arial" COLOR="#0000FF" SIZE="5"><B>DLLE</B></FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">DLLE is the utility to make MSDOS executables, that aren't win32 compatible. Generally this means it creates LE or LX style executables, but there are other options as well.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">DLLE is currently not documented.
</FONT>
<BR><BR><BR>
<A NAME="hs530"></A>
<FONT FACE="Arial" COLOR="#0000FF" SIZE="5"><B>DLMZ</B></FONT><BR>
<BR>
<BR>
<FONT FACE="Arial" SIZE="2">DLMZ is the postprocessor used to create DOS 16-bit executables.There is quite a bit of linker defaults built around it; normally it will be called by the linker in response to use of a linker /T switch that specifies an MSDOS output format.. It would be rare for a user to need to call it directly.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">The general form of a DLMZ command line is:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">dlmz[options] relffile</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Here the relfile is the linker generated file that holds the completely linked code. For example:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">dlmz test.rel</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">makes a console application called test.exe from the linked code in test.rel.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">The following is a list of the command line switches that DLMZ supports.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">/oname - specify output name</FONT><BR>
<FONT FACE="Arial" SIZE="2"> By default, DLMZ will take the input file name, and replace the extension with the extension .EXE.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> However in some cases it is useful to be able to specify the output file name with this switch. The specified name can have its extension specified, or it can be typed without an extension to allow dlhex to add one of the default extensions. For example:</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> dlmz /mREAL /omyfile test.rel</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">makes a segmented executable called myfile.exe</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">/mxxx - specify output type</FONT><BR>
<FONT FACE="Arial" SIZE="2"> DLMZ supports two types of MSDOS executables with the /m switch, as follows:</FONT><BR>
<BR>

<LI><FONT FACE="Arial" SIZE="2">TINY - a tiny-mode program&nbsp;&nbsp;</FONT>
<LI><FONT FACE="Arial" SIZE="2">REAL - a segmented program</FONT><BR>
<FONT FACE="Arial" SIZE="2">&nbsp;&nbsp;</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> The default output format if no /m switch is specified is REAL.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Note that this toolchain isn't compatible with the normal MSDOS build process. Normally,MSDOS programs would have sections that also included something called a class name; the linker would take both the class name and the section name into account when determining how to create an output file. Class names aren't supported by this toolchain, instead it is preferred to write a linker specification file to specify how the sections should be combined. A generic linker specification file exists for each of the supported modes, however, since sections can be named and placed arbitrarily, this specification file would not work for all programs. It may be necessary to augment an MSDOS program with its own specific linker specification file.&nbsp;</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">In tiny mode, it is customary to instruct most MSDOS assemblers to set a code origin of 100h. However, the linker specification file fortiny mode automatically sets this origin. Therefore it does not have to be present for this toolchain to generate tiny mode files. Such files still must start with a code sequence, however.
</FONT>
<BR><BR><BR>
<A NAME="hs540"></A>
<FONT FACE="Arial" COLOR="#0000FF" SIZE="5"><B>DLPE</B></FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">DLPE is the postprocessor used to create Win32 executables. There is quite a bit of linker defaults built around it; normally it will be called by the linker in response to use of a linker /T switch that specifies a WIN32 output format.. It would be rare for a user to need to call it directly.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">The general form of a DLPE command line is:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">dlpe [options] relfile [resourcefile]</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Here the relfile is the linker generated file that holds the linked code, and the optional resourcefile can be used to add resources to an executable.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Resource files can be specified on the command line and DLPE will build a resource section for the exectuble. For example:</FONT><BR>
<BR>
<FONT FACE="Courier New" SIZE="2">dlpe test.rel test.res</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">makes a console application called test.exe from the linked code in test.rel, using resources as specified in test.res.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2">Following is a list of command line switches DLPE supports.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"><B>/oname </B>- specify output name</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> By default, DLPE will take the input file name, and replace the extension with the extension .EXE to form an output file name. However in some cases it is useful to be able to specify the output file name. The specified name can have its extension specified, or it can be typed without an extension to allow dlhex to add one of the default extensions. The output file name is specified with this switch. For example:</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> dlpe /mGUI /omyfile test.rel</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> makes a windowing executable called myfile.exe.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"><B>/mxxx</B> specify the output file format</FONT><BR>
<FONT FACE="Arial" SIZE="2"> DLPE supports several types of WIN32 Executables with the /m switch. the switch is followed by one of the folowing:</FONT><BR>
<BR>

<LI><FONT FACE="Arial" SIZE="2">CON - a console application</FONT>
<LI><FONT FACE="Arial" SIZE="2">GUI - a windowing application</FONT>
<LI><FONT FACE="Arial" SIZE="2">DLL - a DLL</FONT><BR>
<FONT FACE="Arial" SIZE="2">&nbsp;&nbsp;</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> The default output format if no /m switch is specified is the console format.</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"><B>/sname</B> set stub file</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> By default DLPE will add an MSDOS stub file which simply says that the program requires WIN32, if someone happens to run it on MSDOS.&nbsp; However, with the /s switch a specific stub can be specified.&nbsp; This might be useful for example with certain MSDOS DPMI extenders that mimic the WIN32 API for console mode programs. This switches adds a custom stub.&nbsp;&nbsp; For example:</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> dlpe /smystub.exe test.rel</FONT><BR>
<BR>
<FONT FACE="Arial" SIZE="2"> creates an output file test.exe which has the 16-bit program mystub.exe as its MSDOS stub.</FONT><BR>

<BR><BR><BR>
</BODY></HTML>
